Overview

This guide demonstrates how to use the JSON REST API.  The guide uses the cURL command-line tool (available in both Linux and Windows) but the same elements apply no matter what library or tool you are using to interact with the REST API.

View incoming links.

• Discrete Facets ,
• Filter-Based Facets ,
• JSON REST API ,
• Range Facets ,
• Schema Facet

Experimenting with the REST API

The examples on this page use the cURL command-line tool to issue JSON REST API commands.  For instance, this is a very simple query using cURL.  It uses the default Simple Query Language to search for the word "thousand":

C:\>curl -H "Accept:application/json" -H "Content-Type:application/json"
http://blue5:17000/rest/searchApi/search -d "{\"query\": \"thousand\"}"

There are two header parameters stating that this is a JSON request.  The URL connects to the search port of a running AIE instance. The JSON query takes the forms of field/value pairs, as in "query: thousand".  Results are returned in the Command Window as a continuous string (with no formatting). This is not very convenient if you need to examine the results.  (Note that double-quotes inside the query string need to be escaped in cURL.)

We strongly encourage the use of one of the REST clients listed on the JSON REST API page primarily because they return formatted results. The cURL examples below serve as a lowest common denominator for REST API exploration. It is easy to convert the cURL syntax to fit the REST tools.

For instance, this is the same JSON REST query as it appears in the Postman tool:

The search results in Postman come back in a clearly-organized format. 

Indexing Content

Adding Content to the Store

First, let's add a PDF file from local disk to the content store that we want to process with id myContentPointerId

curl 'http://localhost:17000/rest/contentStoreApi/put/aie.default/myContentPointerId' --data-binary '@somePath/somefile2upload.pdf'

Creating a REST Ingest API session (connect)

Next, we need to create a REST Ingest API session in order to perform any ingestion-related tasks. We specify the fileIngest workflow for this session.

$ curl -H 'Accept:application/json' -H 'Content-Type:application/json' 'http://localhost:17000/rest/ingestApi/connect' -d '{ "ingestWorkflowName" : "fileIngest" }'

This command will return a session id in the form of a JSON string, along these lines:

"ad9b1452-549b-4006-b4a4-b37e0fa934c3"

We will need to specify this session ID in all future ingestion-request URLs, as shown in the commands below. Replace this sample session ID with the one from your connect response when running these commands.

Feeding documents

Next, we feed two documents, one with a contentpointerid field value matching the content ID we created above:

curl -H 'Content-Type:application/json' 'http://localhost:17000/rest/ingestApi/feedDocuments/ad9b1452-549b-4006-b4a4-b37e0fa934c3' -d '[ {
  "id" : "1",
  "fields" : {
    "title" : [ "this is the first title" ],
    "date" : [ "1969-12-31T19:00:10.000-0500" ],
    "cat" : [ "cat1" ],
    "contentpointerid" : [ "myContentPointerId" ]
  }
}, {
  "id" : "2",
  "fields" : {
    "title" : [ "this is the second title" ],
    "date" : [ "1969-12-31T19:00:20.000-0500" ],
    "cat" : [ "cat2" ]
  }
} ]'

Committing Documents

Now we commit the indexed documents:

curl 'http://localhost:17000/rest/ingestApi/commit/ad9b1452-549b-4006-b4a4-b37e0fa934c3'

Disconnecting

Lastly, we disconnect the REST Ingest API session to free up system resources:

curl 'http://localhost:17000/rest/ingestApi/disconnect/ad9b1452-549b-4006-b4a4-b37e0fa934c3'

For more information on content ingestion please refer to the REST Ingest API page.

Searching Content

Run a search for the documents using CGI arguments.

curl -H 'Accept:application/json' 'http://localhost:17000/rest/searchApi/simpleCgi?q=*&facet=cat'

You can run the same search by posting a search request in JSON as well

curl -H 'Accept:application/json' -H 'Content-Type:application/json' 'http://localhost:17000/rest/searchApi/search' -d '{
    "query": "*",
    "facets": [ "cat" ]
}'

The search results are then returned in a JSON format as follows 

{
    "totalTime": 3,
    "totalHits": 2,
    "documents": [
        {
        "fields": {
                "title": [ "this is the first title" ],
                "date": [  "1969-12-31T19:00:10.000-0500" ],
                "text": [ "This is the text of my PDF file.  It was extracted in the fileIngest workflow" ],
                ".zone": [ "default" ],
                ".id": [ "1" ], 
                ".score": [ 167 ]
            }
        },
        {
            "fields": {
                "title": [ "this is the second title" ],
                "date": [ "1969-12-31T19:00:20.000-0500" ],
                ".zone": [ "default" ],
                ".id": [ "2" ],
                ".score": [ 167 ]
            }
        }
    ],
    "facets": [
        {
            "label": "Category",
            "buckets": [
                {
                    "label": "cat1",
                    "filter": "CONTEXT(cat, facet=true, filter=true):PHRASE(cat1, query=cat1, tokenize=false)",
                    "count": 1
                },
                {
                    "label": "cat2",
                    "filter": "CONTEXT(cat, facet=true, filter=true):PHRASE(cat2, query=cat2, tokenize=false)",
                    "count": 1
                }
            ]
        }
    ]
}

For more information on querying for content please refer to the REST Query API page.