In a system in which requirements remain fairly static, or at least predictable, the LucidWorks user interface may be sufficient for managing your system. For more complex or dynamic systems, LucidWorks Search provides programmatic, remote access to many aspects of configuration and operation through a REST API. All tasks that can be accomplished with the Admin UI can also be done with the REST API. Some of the more complex administration tasks are available through the API only.
The LucidWorks Search REST APIs focus on administrative tasks of manipulating settings, fields, data sources, and other configuration options as well as some system monitoring functions. Programmatic access to search itself is by making GET requests to Solr directly, as documented in the section Getting Search Results. The Apache Solr Reference Guide also contains a great deal of information about searching Solr.
The LucidWorks Search APIs use GET, POST, PUT and DELETE requests. The results of a REST request depend not only on the type of request, but on whether you called it on an object or group of objects. When you use REST requests with LucidWorks, you send a JSON request to the endpoint specified for the object (or group) you want to work with. The system then sends back the results as a JSON object. Currently, LucidWorks only recognizes JSON requests.
|About Server Addresses in the API Documentation|
The LucidWorks Search REST API uses the Core component, installed at http://localhost:8888/ by default and many examples in this Guide use this as the server location. If you changed this location on install, or if you are using LucidWorks Search hosted on Azure or AWS, be sure to change the destination of your REST requests.
If using LucidWorks Search hosted by LucidWorks in AWS or Azure, the server call must include the API Key used as authentication credentials. This is basic authentication, and your instance will have a URL with "https://s-XXXXXXXX.lucidworks.io" where XXXXXXXX is 8 characters (letters or numbers). So, if your instance URL is "https://s-9sdff10b.lucidworks.io/" you would use that in place of any example API calls that used "http://localhost:8888". For example, this call to get all collections:
would be changed to:
curl -u 'API_Key:password' 'https://s-9sdff10b.lucidworks.io/api/collections'
The API_Key can be found by logging in to your LucidWorks Search hosted instance, and clicking "My Account" at the upper right of the screen. Click "API Access" on the left to view the API key. The password is 'x' by default. There is not currently a way to change the default password so you should take care not to expose this key when posting to our forums, as that information is publicly available to other customers.
For users hosted on Windows Azure, the above URL would be: 'https://s-9sdff10b.azure.lucidworks.io/api/collections'
A few pages give examples of using the APIs in configuring and managing a LucidWorks-based search application.
- Getting Started Indexing gives an overview of the calls required to set up a data source and index content.
- Error Response Format shows the format of errors if the calls go wrong.
- Overview of REST API calls provides a quick reference of the APIs and what they do.
- Advanced Operations Using the REST API contains examples of more advanced tasks, such as creating and editing fields, monitoring data sources, and configuring users.
- Example Clients includes three sample clients (in Perl, Python and C#) that were implemented using the REST API.
- Version: Shows information about the LucidWorks and Solr versions being used by the system.
- Collections: Groups of documents that are logically separate.
- Collection Information: Get information about the collection.
- Collection Templates: Get information about templates that can be used when creating new collections.
- Collection Index Delete: Delete the entire index or only data from a single data source.
- Activities: Control schedules for resource-intensive operations such as optimization and building indexes.
- Data Sources: The conduits by which data enters LucidWorks indexes.
- Batch Crawling: Create and manage crawling when the data shouldn't be indexed until a later time.
- JDBC Drivers: Load required JDBC drivers for database indexing.
- lweug:Field Types: Create new field types or modify existing types.
- Fields: How data from a single document is organized in LucidWorks indexes.
- Dynamic Fields: Define dynamic fields for on-the-fly field creation based on specific patterns.
- Filtering Results: Use Access Control Lists to filter results for Windows Shares.
- Search Components: List active search components for a particular search handler.
- lweug:Settings: Many different query- and index-time settings.
- Caches: Configure how Solr caches documents to speed results.
- Click Scoring: Integrate Click Scoring with your own search application to record which documents are most popular with users.
- Roles: Configure search filters to control access to documents.
- Alerts: Create and modify alerts for users.
- Users: Create user accounts (if not using an external user management system, such as LDAP).
- SSL Configuration: Configure LucidWorks to work with SSL.
- Crawler Status: Status of communication with the Connectors component.
|When creating or updating a resource (using a POST or a PUT), you generally only need to include those entries in your map that you need to set. When LucidWorks creates a resource, entries you omit will get their default values. When you update a resource, entries you omit will retain their previous values.
JSON primitives can be used and will be returned, but LucidWorks also accepts string parsable equivalents. For example, both 4 or "4" are valid inputs for an integer type, but 4 will be returned by the REST API.
APIs that take a list will also take a single variable (for example, a list<string> accepts string) and treat it as a list of size 1.
For convenience, you can append ".json" to any method.