Sample REST API scenarios

The sample programs are installed in the ES_INSTALL_ROOT/samples/rest directory. Documentation about the REST API is available in the ES_INSTALL_ROOT/docs/api/rest directory.

• Search
• Faceted search against single index

For the administration REST APIs, several sample REST API Java™ programs are provided. The programs illustrate two different methods of using the REST APIs: Apache HttpClient or Java API for XML Web Services (JAX-WS). The sample programs must be compiled and their class files are in the ES_INSTALL_ROOT/samples/rest/admin/es.admin.rest.jar file.

HttpClient sample programs

The following REST API sample programs for HttpClient are provided in the ES_INSTALL_ROOT/samples/rest/admin/com/ibm/es/admin/control/api/samples/commons directory:

DocumentExample sample program

The DocumentExample class provides an example of how to add or remove a document in a collection. The sample program allows you to add a document to a collection and remove a document from the collection. The type of function depends on the method that you input as a command argument. This program requires that a collection was already created.

The program builds the HTTP request based on the specified host name, port, method, collection ID, and other options. It uses the user name and password to perform authentication. With the HTTP request, the program obtains the HTTPMethod object that is executed by HttpClient. For the add and addMultiDocs functions, the program uses the file path of an existing file and some of the metadata of the document to add the file content as a document in the collection.

The usage statement is as follows:

DocumentExample -hostname host_name -port port -method method 
-username user_name -password password -collectionId collection_ID 
additional_parameters

The following example shows how to add the content of the C:\samples\sample1.txt file as an English document in the col_12345 collection:

DocumentExample -hostname es.ibm.com -port 8390 -method add 
-username user1 -password mypassword -collectionId col_12345 
-language en -file C:\samples\sample1.txt

AddMultiDocsExample sample program

The AddMultiDocsExample class provides an example of how to add two sample documents, a PDF file and an HTML file, to a collection. This program requires that a collection was already created.

The program builds the HTTP POST request based on the specified host name, port, collection ID, and other parameters. The program specifies the document ID, title, format, and language of the documents in JSON format as the value of the docs parameter and the content of the documents is specified as the value of the file parameter. The program uses the specified user name and password to perform authentication. With the HTTP request, the program obtains the HTTPMethod object that is executed by HttpClient.

The usage statement is as follows:

AddMultiDocsExample -hostname host_name -port port -username user_name 
-password password -collectionId collection_ID

The following example shows how to add the documents to the col_12345 collection:

AddMultiDocsExample -hostname es.ibm.com -port 8390 -username user1 
-password mypassword -collectionId col_12345

Field administration sample program

The FieldExample class provides an example of performing the available methods on search fields within a collection.  It allows you to add a search field, list the fields, map a search field to a crawler, map the search field to a facet, and remove a search field from the collection. The type of field function depends on the method that you input as a command argument. This program requires that a collection was already created.

It builds the HTTP Request URL based on the inputted host name, port, method, and other options. It uses the inputted user name and password to perform authentication. With the HTTP request, the program obtains the HTTPMethod object that is executed by HttpClient.

The usage statement is as follows:

FieldExample -hostname host_name -port port -method method
 -username user_name -password password additional_parameters

The following shows an example of obtaining a list of fields for the col_12345 collection:

FieldExample -hostname es.ibm.com -port 8390 -method getList 
-username user1 -password mypassword -collectionId col_12345

GetAccess sample program

The GetAccess example shows how to use REST API by directly inputting the URLs. You need to pass the URL with required parameters to this program. It then executes the HTTPMethod based on the URL that you pass in as an argument and prints the HTTPMethod response. 

The usage statement is as follows:

GetAccess URL -username user_name -password password

The following example shows how to obtain the state of the index in xml format for the Test collection.

GetAccess "http://localhost:8390/api/v10/admin/indexer?
method=getState&output=xml&collectionId=Test" -username esadmin 
-password password

IndexerExample sample program

The IndexerExample class shows how to perform various operations on the index, such as start and stop the index and get the state of the indexer. The type of function depends on the method that you input as a command argument.

The usage statement is as follows:

IndexerExample -hostname host_name -port port -method method 
-username user_name -password password

The following example shows to start the index for the col_12345 collection.

IndexerExample -hostname es.ibm.com -port 8390 -username esadmin 
-password password -method start -collectionId col_12345

Administering PEAR files sample program

The PearExample shows how to manipulate a custom annotator PEAR file. The program allows you to add a PEAR file to the system, associate and disassociate it with a collection, obtain a list of deployed PEAR files, and remove a PEAR file from the system. The type of function depends on the method that you input as a command argument.

The usage statement is as follows:

PearExample -hostname host_name -port port -method method 
-username user_name -password password additional_parameters

The following example shows how to add the of_regex.pear PEAR file and name it RegexPear in Watson Explorer Content Analytics.

PearExample -hostname es.ibm.com -port 8390 -method add 
-username esadmin -password password -pearName RegexPear 
-content "C:\\IBM\\es\\packages\\uima\\regex\\of_regex.pear"

JAX-WS sample programs

The following REST API sample programs for JAX-WS are provided in the ES_INSTALL_ROOT/samples/rest/admin/com/ibm/es/admin/control/api/samples/jaxws directory:

Administering facets sample program

The FacetExample shows how to work with facets for a specified collection by using the JAX-WS service to access the REST API. Some of the available functions for the Facet API include adding and removing a facet from a specified collection and obtaining a list of facets. The type of function depends on the method that you input as a command argument.

The usage statement is as follows:

FacetExample -hostname host_name -port port -method method 
-username user_name -password password additional_parameters

The following example shows how to obtain a list of facets for the col_12345 collection. 

FacetExample -hostname es.ibm.com -port 8390 -method getList 
-username esadmin -password password -collectionId col_12345

GetAccess sample program

The GetAccess example shows how to use REST API by directly inputting URLs You need to pass the URL with required parameters to this program. It then invokes the JAX-WS service to invoke the REST API based on the URL that you passed in as an argument and prints the result stream. 

The usage statement is as follows:

GetAccess URL

The following example shows how to obtain the state of the indexer for the Test collection.

GetAccess “http://localhost:8390/api/v10/admin/indexer?
method=getState&output=xml&collectionId=Test
&api_username=esadmin&api_password=password”

Administering PEAR files sample program

The PearExample shows how to manipulate a custom annotator PEAR file by using the JAX-WS service to access the REST API.  It allows you to add a PEAR file to the system, associate and disassociate it with a collection, obtain a list of deployed PEAR files, and remove a PEAR file from the system. The type of function depends on the method that you input as a command argument.

The usage statement is as follows:

PearExample -hostname host_name -port port -method method 
-username user_name -password password additional_parameters

The following example shows how to add the of_regex.pear PEAR file and name it RegexPear in Watson Explorer Content Analytics.

PearExample -hostname es.ibm.com -port 8390 -method add 
-username esadmin -password password -pearName RegexPear 
-content "C:\\IBM\\es\\packages\\uima\\regex\\of_regex.pear"