REST APIs

The Watson Explorer Content Analytics REST application programming interfaces (APIs) enable you to create applications to search, explore, and administer collections.

REST (REpresentational State Transfer) APIs rely on a stateless, client-server, cacheable communications protocol. REST applications use HTTP requests to post data (create and update), read data (such as running queries), and delete data. REST is a lightweight alternative to mechanisms like RPC (Remote Procedure Calls) and Web Services (such as SOAP and WSDL). Much like Web Services, a REST service is:
  • Platform-independent

  • Language-independent

  • Standards-based (runs on top of HTTP)

  • Able to be used in the presence of firewalls

The REST APIs provide capabilities that IBM search and index APIs (SIAPI) offer, such as:
  • Managing collections

  • Controlling and monitoring components

  • Adding documents to a collection

  • Searching a collection and federated collections

  • Searching and browsing facets

The REST APIs offers the following benefits:
  • Language independent and pure remote calls.

  • No special client modules are required to call the API.
  • Easy to understand and use. Almost all communication between client and server are in text format, and you can use your web browser to try the API.

  • Because any client that supports HTTP can use the REST API, you can build client applications on various platforms.

REST API categories

The REST API consists of two categories of APIs:

The search REST API is available on search servers and listens on the search application port, which by default is port 8393 if you use the embedded web application server. If you use WebSphere Application Server, the default port is 9081 or 80 if IBM HTTP Server is configured. The administrative REST API is available on the master server if you use the embedded web application server and uses the same port number as the administrative console, which by default is 8390. If you use WebSphere Application Server, the administrative REST API is available on the search application port, which by default is 9081 or 80 if IBM HTTP Server is configured. You can change these port numbers when you install Watson Explorer Content Analytics.

Authentication

When application server login is properly configured, BASIC authentication is required for the administration and search REST APIs. In addition, the administration REST API needs to be authenticated with the api_username and api_password keywords.

HTTP methods

You can use both HTTP GET and HTTP POST methods to call most REST APIs. For the HTTP GET method, you can directly enter a REST API URL into a web browser. The POST method is recommended for security reasons.

REST API URLs

The base URI for the REST APIs is:

http://host:port/api/v10/

For the administration REST APIs, create URLs in the following format:

http://Index_server_hostname:Administration_console_port/api/v10/admin/API_name?method=method_name?parameters

For example, use the following administration REST API URL to return information about the status of the index:

http://Index_server_hostname:8390/api/v10/admin/indexer?method=monitor&api_username=user_name&api_password=password&collectionId=collection_ID

For the search REST APIs, create URLs in the following format:

http://Search_server_hostname:Search_server_port/api/v10/API_name?parameters

For example, use the following search REST API URL to return a list of all available namespaces of facets for the specified collection:

http://Search_server_hostname:8393/api/v10/facets/namespaces?collection=sample

The /about/providers API returns all available search REST APIs. The /about/providerdetail API returns detailed information about all the available search REST API. These APIs are especially useful if you develop an application that uses the REST API and you cannot access a computer on which Watson Explorer Content Analytics is installed to view the REST API reference documentation.

For example, place the following URL in a web browser:

http://Search_server_hostname:8393/api/v10/about/providerdetail?path=/collections&output=application/xml

Tips:
  • To create proper URLs, ensure that they are URL encoded. For example, output=application/atom+xml should be eencoded as output=application/atom%2Bxml.
  • Try REST API calls in a browser before using them in a program. Trying a REST API call in a browser gives you an opportunity to see the output from the REST API call before you attempt to parse it in your application.\
  • In order to arrive at the necessary result, you might need a series of API calls.
  • Ensure that search queries conform to the Watson Explorer Content Analytics query syntax. For example, if you want to search for a phrase, the query parameter phrase value must be in double quotation marks.

For more information about using the REST APIs, see the API documentation in the ES_INSTALL_ROOT/docs/api/rest directory. Sample scenarios that demonstrate how to perform administrative and search tasks are available in the ES_INSTALL_ROOT/samples/rest directory.

Restriction: The following functions are not available in the REST API:
  • com.ibm.es.siapi.admin.AdminServiceImpl.associateApplicationWithCollection

  • com.ibm.es.siapi.admin.AdminServiceImpl.associateApplicationWithCollection

  • com.ibm.es.siapi.admin.AdminServiceImpl.registerApplication

  • com.ibm.es.siapi.admin.AdminServiceImpl.unregisterApplication

  • com.ibm.es.siapi.admin.AdminServiceImpl.disassociateApplicationFromCollection

  • com.ibm.es.siapi.admin.AdminServiceImpl.performAdminCommand (changeRankingModel and revisitURLs options)