RESTful API - Control Messages

The SRCH2 engine supports certain control messages through its RESTful API. Here we explain how to use the messages to manage the engine. Each RESTful request needs to use a proper URL encoder to be converted to characters in a format that can be transmitted properly.

1. Retrieving System Status

This request returns the information about the system status. The response body will contain a JSON map with these fields:

Here is an example query:

 curl -i "http://127.0.0.1:8081/info"

Here is an example response:

 HTTP/1.1 200 OK
 Content-Type: application/json; charset=UTF-8
 Content-Length: 138
 Date: Thu, 19 Sep 2013 18:52:52 GMT

 {"engine_status":{"search_requests":"0","write_requests":"100","docs_in_index":"100","last_merge":"02/10/14 23:11:21","last_merge_time":"0","doc_count":"100"}, "version":"4.2.0"}

2. Serializing Indexes to Disk

This request tells the engine to serialize the indexes, with all the changes made so far, to files in the path specified by the parameter "dataDir" in the configuration file. Here is an example:

 curl -i "http://127.0.0.1:8081/save" -X PUT

3. Serializing Records to Disk

This request tells the engine to serialize the records, with all the changes made so far, to a file in the path specified by the parameter "dataDir" in the configuration file. Deleted records will be ignored. The request can specify the file name as well, using a variable called "exported_data_file". Here is an example:

 curl -i "http://127.0.0.1:8081/export?exported_data_file=mydata.json" -X PUT

The engine will store the records in the file "mydata.json" in the folder specified by the parameter "dataDir".

4. Reseting Log File

This API is used by a third-party tool such as logrotate to manage the log file. Suppose the "logrotate" tool has renamed the log file "srch2-log.txt" to another file "srch2-log.txt.1". The tool also has re-created a file with the original name "srch2-log.txt". The SRCH2 engine is still writing log messages to the file "srch2-log.txt.1". Now "logrotate" sends the following message:

 curl -i "http://127.0.0.1:8081/resetLogger" -X PUT

It tells the SRCH2 engine to reset its log-file handle to continue using the original file name "srch2-log.txt". In this way, the old log messages have been moved to the file ""srch2-log.txt.1", which can be managed by the "logrotate" tool. Here is an example configuration file for "logrotate":

 "/home/joe/srch2/logs/srch2-log.txt" {
    weekly
    missingok
    rotate 52
    notifempty
    sharedscripts
    postrotate
            curl -i "http://127.0.0.1:8081/resetLogger" -X PUT
    endscript
    prerotate
    endscript
}

5. Shutdown the server

The client can send a shutdown message to let the server stop gracefully. The request should be sent to the "/_all/shutdown" path by a "PUT" method. Here is an example query:

 curl -i "http://127.0.0.1:8081/_all/shutdown" -X PUT

6. Modify attribute-based access control

The user can add, delete, and modify existing access control map using the following APIs. The modified access control map does not affect the ongoing search. It will be reflected in the subsequent search queries.

6.1. Add a new attribute-based access control

The API aclAttributeRoleAdd adds new access control to the engine. For example, the following HTTP PUT request adds attributes "attr1" and "attr20" into the access control list of the role-ids "1001" and "1002" for the "product" core.

curl -i "http://127.0.0.1:8081/product/aclAttributeRoleAdd" -X PUT -d '{ “attributes”: [“attr1”, “attr20"], “roleId”: ["1001”, “1002"]}'

The aclAttributeRoleAdd request above creates the following access control map in the engine.

"1001" => "attr1" , "attr20"
"1002" => "attr1" , "attr20"

Note: aclAttributeRoleAdd overwrites the existing access control map for a role-id.

6.2. Append to an existing attribute-based access control

The API aclAttributeRoleAppend appends attributes to the existing access control list for a role-id. If the role-id is not found in access control map then the role-id is added. For example, the following HTTP PUT request adds attribute "attr31" to the access control list of the role-id "1001" for the "product" core.

 curl -i "http://127.0.0.1:8081/product/aclAttributeRoleAppend" -X PUT -d '{ “attributes”: [“attr31"], “roleId”: ["1001”]}'

The append command above modifies the access control map in the engine as shown below.

"1001" => "attr1" , "attr20" , "attr31"
"1002" => "attr1" , "attr20"

6.3. Delete an attribute-based access control

The API aclAttributeRoleDelete deletes attributes from the existing access control list for a role-id. If the role-id is not present, then the request will be ignored. If all the attributes for a role-id are deleted, then the role-id is removed from the access control map. For example, the following HTTP PUT request deletes attribute "attr1" from the access control list of the role-id "1001" for the "product" core.

 curl -i "http://127.0.0.1:8081/product/aclAttributeRoleDelete" -X PUT -d '{ “attributes”: [“attr1"], “roleId”: ["1001"]}'

The delete command above modifies the access control map in the engine as shown below.

"1001" => "attr20",  "attr31"   # Note: "attr1" is deleted
"1002" => "attr1" , "attr20"

To delete the whole access control for a particular role-id, use * as a value for the attributes key in the input JSON. For example:

 curl -i "http://127.0.0.1:8081/product/aclAttributeRoleDelete" -X PUT -d '{ “attributes”: [“*"], “roleId”: ["1001"]}'

The above delete command modifies the access control map in the engine as shown below.

"1002" => "field1" , "field20"

7. Adding feedback for search results

The SRCH2 engine has a unique, powerful feature to dynamically boost the ranking of records based on user feedback. Please refer to feedback configuration and feedback ranking for details.

The feedback API allows users to add a feedback for a query. For example, consider the following query:

 curl -i "http://server:port/search?q=trip"

If the user selects a record with id "5" as the answer, the client can send a feedback (possibly using javascript) to the engine by sending the following request:

 curl "http://server:port/feedback" -X PUT -d  '{ query = "trip" , recordId = "5"}' 

The client can also send multiple feedbacks to the server in a single request. The following is an example:

 curl "http://server:port/feedback" -X PUT -d  '[{ query = "trip" , recordId = "5"}, { query = "trip" , recordId = "7"}]' 

It sends to the server two feedbacks, with records "5" and "7" for the same query "trip". This API can be used to reduce the number of interactions between the client and the server, when multiple feedback tuples are stored on the client and sent to the server in a batch.

Notice that the query field in a feedback control's JSON data should be exactly the same as the text in the search query (including the operators), since the engine uses this query field as a key to find queries to boost records. For example, consider the following multi-word query with the "AND" boolean operator:

 curl -i "http://server:port/search?q=trip%20AND%20advisor"

In the example, "%20" is the URL encoding for the white space. A feedback for this query should have exactly the same query field, e.g.:

 curl "http://server:port/feedback" -X PUT -d  '{ query = "trip%20AND%20advisor", recordId = "5"}'