Ben Isherwood

Integrating to Content Intelligence REST APIs

Blog Post created by Ben Isherwood Employee on Mar 14, 2018

Here's a quick start guide to help you to integrate to Content Intelligence REST APIs!

 

All of the features available in the Admin and Search UI applications are also available via both the CLI and REST API.

 

Content Intelligence provides 2 distinct REST APIs:

  • Admin - Used to configure and manage a system
  • Search - Used to query across search engine indexes

 

 

REST UI

 

Both the Admin and Search applications in Content Intelligence provide Swagger REST API UI tool for each of their respective APIs.

 

The admin REST API UI can be found in any deployed Content Intelligence system here on the default admin port:

https://<host-ip>:8000/doc/api/

 

The search REST API UI can be found here, on the default search port:

https://<host-ip>:8888/doc/api/

 

searchRESTUI.jpg

 

This REST UI tool documents and demonstrates the entire REST API, allowing you to exercise real request/responses, list and manage system state, display curl examples, etc. This tool has proved invaluable in accelerating product integrations with Content Intelligence, while demonstrating it's capabilities.

 

Expand an API to see it's request/response model objects:

RESTUI1.PNG

 

 

Click "Try it out!" to run a request against the live service to see it's behavior (and get a curl example):

RESTUI2.PNG

 

 

Authentication

 

How does Content Intelligence handle authentication?

 

We use OAuth framework to generate access tokens. The process works as follows:

 

1. Request an access token

 

Once you have a user account, you need to request an authentication token from the system. To do this, you send an HTTP POST request to the /auth/oauth endpoint on the application you're using.

 

Here's an example using the cURL command-line tool:

curl -ik -X POST https://<system-hostname>:8000/auth/oauth/ \

-d grant_type=password \

-d username=<your-username> \

-d password=<your-password> \

-d scope=* \

-d client_secret=hci-client \

-d client_id=hci-client \

-d realm=<security-realm-name-for-an-identity-provider-added-to-HCI>

 

In response to this request, you receive a JSON response body containing an access_token field. The value for this field is your token. For example:

{ "access_token" : "eyJr287bjle..." }

 

2.  Submit your access token with each REST API call

 

You need to specify your access token as part of all REST API requests that you make. You do this by submitting an Authorization header along with your request. Here's an example that uses cURL to list the instances in the system:

curl -X GET --header "Accept:application/json" https://<system-hostname>:<admin-app-port>/api/admin/instances --header "Authorization: Bearer <your-access-token-here>"

 

Notes:

 

• This same mechanism works with local admin users and remote directory servers (e.g. "identity providers"). To get a list of security realms available in the system, send an HTTP GET request to the /setup endpoint. This can be used to let users select the type of authentication credentials they will be providing. For example, to do this with cURL to get the list of realms:

curl -X GET --header 'Accept: application/json' 'https://<hostname>:<admin-app-port>/api/admin/setup'

• To get an access token for the local admin user account, you can omit the realm option for the request, or specify a realm value of "Local".

• If a token expires (resulting in a 401 Unauthorized error), you may need to generate a new one the same way as before. This expiration duration is configurable in the Admin App.

 

 

Workflow Admin

 

List all instances in the system:

curl -X GET --header 'Accept: application/json' 'https://cluster110f-vm3:8000/api/admin/instances'

 

List all workflows in the system:

curl -X GET --header 'Accept: application/json' 'https://cluster110f-vm3:8000/api/admin/workflows'

 

Run a specific workflow:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' 'https://cluster110f-vm3:8000/api/admin/workflows/1f7a6156-4a64-4ac0-b2e8-d73f691dea73/task'

 

Simple Search Queries

 

Querying Content Intelligence search indexes generally involves:

  • List the indexes in the system.
    • Index name is a required input for querying indexes (federated or otherwise).
  • Submit a query request, and obtain a response.
    • There are a number of queries users can perform, the most basic of which is a simple query string. When there are many results, the API also supports paging and limits on responses.

 

List all indexes in the system:

curl -X GET --header 'Accept: application/json' 'https://cluster110f-vm3:8000/api/admin/indexes'

 

Submit a simple query request:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{

  "indexName": "Enron",

  "queryString": "*:*",

  "offset": 0,

  "itemsToReturn": 1

}' 'https://cluster110f-vm3:8888/api/search/query'

 

Query results returned:

{

  "indexName": "Enron",

  "results": [

    {

      "metadata": {

        "HCI_snippet": [

          "Rhonda,\n\nYou need to check with Genia as I have never handled the physical power agreement matters.\n\nSusan \n\n -----Original Message-----\nFrom: \tDenton, Rhonda L.  \nSent:\tTuesday, January 15, 2002 2:17 PM\nTo:\tBailey, Susan\nCc:\tHansen, Leslie\nSubject:\tSouthern Company Netting\n\nHere's Southern.  I never received a copy of the Virginia Electric Master Netting.  We do have netting within the EEI.\n << File: 96096123.pdf >> \n\n"

        ],

        "Content_Type": [

          "message/rfc822"

        ],

        "HCI_dataSourceUuid": [

          "f1c05be1-5947-41e1-a9f1-03a98f0fa036"

        ],

        "HCI_id": [

          "https://ns1.ten1.cluster27d.lab.archivas.com/rest/enron/maildir/bailey-s/deleted_items/25."

        ],

        "HCI_doc_version": [

          "2015-07-02T09:06:02-0400"

        ],

        "HCI_displayName": [

          "RE: Southern Company Netting"

        ],

        "HCI_URI": [

          "https://ns1.ten1.cluster27d.lab.archivas.com/rest/enron/maildir/bailey-s/deleted_items/25."

        ],

        "HCI_dataSourceName": [

          "HCP Enron"

        ]

      },

      "relevance": 1

      "id": "https://ns1.ten1.cluster27d.lab.archivas.com/rest/enron/maildir/bailey-s/deleted_items/25.",

      "title": "RE: Southern Company Netting",

      "link": "https://ns1.ten1.cluster27d.lab.archivas.com/rest/enron/maildir/bailey-s/deleted_items/25."

    }

  ],

  "facets": [],

  "hitCount": 478

}

 

Outcomes