LucidWorks provides the ability to programmatically control administrative functions using the REST API.
To use the REST API, you send a JSON object via an HTTP request. For example, you can use the REST API to dynamically create a field:
curl -d '{
"name": "new_field",
"term_vectors": true,
"default_value": "lucid rocks",
"use_for_deduplication": true,
"multi_valued": true,
"stored": true,
"indexed": true,
"search_by_default": false,
"facet": true,
"index_for_spellcheck": true,
"synonym_expansion": true,
"short_field_boost": "moderate",
"field_type": "text_en"
}' -H 'Content-type: application/json' 'http://localhost:8888/api/collections/collection1/fields'
The request returns a JSON representation of the created object:
{
"default_boost":1.0,
"field_type":"text_en",
"facet":true,
"indexed":true,
"short_field_boost":"moderate",
"term_vectors":true,
"include_in_results":false,
"stored":true,
"omit_tf":false,
"highlight":false,
"editable":true,
"search_by_default":false,
"user_field":true,
"multi_valued":true,
"default_value":"lucid rocks",
"use_for_deduplication":true,
"name":"new_field",
"synonym_expansion":true,
"index_for_spellcheck":true,
"index_for_autocomplete":false,
"query_time_stopword_handling":false,
"copy_fields":["text_medium","text_all","spell"],
"use_in_find_similar":false}
As with all operations against LucidWorks, you have the option to use any HTTP client to perform these operations, as long as they use the proper methods, as documented under REST API.
Perhaps the most common usage of the REST API is to control and monitor data sources and indexing. Consider this example, from Getting Started Indexing. First, you create the data source:
curl -H 'Content-type: application/json' -d '{
"crawler":"lucid.aperture",
"type":"web",
"url":"http://www.lucidimagination.com/",
"crawl_depth":1,
"name":"Lucid Website"
}'
http://localhost:8888/api/collections/collection1/datasources
The response includes the id value (it is quite long, so it's been truncated here):
{
"add_failed_docs": true,
"auth": [],
"bounds": "none",
"caching": false,
"category": "Web",
"collection": "collection1",
"commit_on_finish": true,
"commit_within": 900000,
"crawl_depth": -1,
"crawler": "lucid.aperture",
"exclude_paths": [ ],
"fail_unsupported_file_types": true,
"id": 3,
"ignore_robots": false,
"include_paths": [ ],
"indexing": true,
"log_extra_detail": false,
"mapping": {
...
},
"max_bytes": 10485760,
"max_docs": -1,
"name": "Lucid Website",
"parsing": true,
"proxy_host": "",
"proxy_password": "",
"proxy_port": -1,
"proxy_username": "",
"type": "web",
"url": "http://www.lucidimagination.com/",
"verify_access": true,
"warn_unknown_mime_types": true
}
The next step is to tell LucidWorks to start indexing the documents by submitting a job request:
curl -X PUT http://localhost:8888/api/collections/collection1/datasources/3/job
This request does not return anything, but it does start the index running. To check the status, we send a GET request:
curl http://localhost:8888/api/collections/collection1/datasources/3/status
This request tells us that the data source is still being indexed:
{
"batch_job": false,
"crawl_started": "2012-02-06T18:40:12+0000",
"crawl_state": "RUNNING",
"crawl_stopped": null,
"id": 3,
"job_id": "6",
"num_access_denied": 0,
"num_deleted": 0,
"num_failed": 2,
"num_filter_denied": 0,
"num_new": 227,
"num_not_found": 0,
"num_robots_denied": 0,
"num_total": 229,
"num_unchanged": 0,
"num_updated": 0
}
Another common use for the REST API is to manage users and alerts. In most cases, you will use an LDAP server to manage users, but you also have the option to manage them internally using the REST API. For example, to create a user, you would send a POST request:
curl -H 'Content-type: application/json' -d '
{
"username": "smiller",
"email": "me@here.com",
"authorization": "search",
"password": "123456"
}' 'http://localhost:8989/api/users'
You can also create an Enterprise Alert, which notifies the user when there are new results for a search. For example, you can create an alert that sends the new user, smiller, notification when there is new data for the search "robot":
curl -H 'Content-type: application/json' -d '{
"name":"Robot search",
"collection":"collection1",
"username":"smiller",
"query":"robots",
"period":86400,
"email":"test@test.com"
}' http://localhost:8989/api/alerts
 | The Users API and Enterprise Alerts do not run on the Solr port; they're handled by the LWE UI component, installed by default on port 8989. |
The request returns a JSON representation of the object, which includes the ID:
{
"id":1,
"name":"Robot search",
"collection":"collection1",
"username":"smiller",
"query":"robots",
"checked_at":"2012-06-07T14:22:54Z",
"period":86400,
"email":"me@here.com"
}
You can then use that ID to check the status of the alert:
curl -X PUT http://localhost:8989/api/alerts/1/check
In this case, we have not yet seen any new results:
{
"checked_at": "2012-06-07T14:22:54Z",
"collection": "collection1",
"email": "me@here.com",
"id": 1,
"name": "Robot search",
"period": 86400,
"query": "robots",
"username": "smiller"
}
