APIs

When you open an API you see an overview of all the endpoints it contains. Endpoints can be used by an application to communicate with the data in Sparque Desk. The Sparque REST API (Representational state transfer Application Programming Interface) is used to define the request messages as well as the type of response messages.

The screenshot below shows the API endpoints that are defined for a sample movie application. Six different API endpoints are defined:

• An endpoint that finds movies based on a text query from a search box,
• An autocomplete endpoint,
• A movie endpoint that retrieves the details of a specific movie,
• A related_movies endpoint that recommends movies for a specific movie,
• Two endpoints that drive a genre facet.

The request URL consists of several elements. Let's take a look at the example below. This request URL is used to query the data using a keyword and a user-id. It returns personalized search results:

https://rest.sparque.ai/2.5/{WORKSPACE}/api/e/{ENDPOINT}/p/keyword/{STRING}/p/user-id/{STRING}/results

• rest.sparque.ai represents the domain.
• 2.5 represents the used version of Sparque Desk.
• /{WORKSPACE} represents the workspace where the data resides.
• /{ENDPOINT} represents the endpoint that queries the data.
• /p/keyword/{STRING} represents the keyword parameter, of data type STRING, to be used in the query. The data type of each parameter is configurable, as is the number of parameters.
• /p/user-id/{STRING} represents the user parameter, of data type STRING, to be used in the query.
• /results represents the type of request, in this case a result list.

In the current version (version 2.4), the queried strategy is identified by a unique commit_id. This commit_id is displayed for each committed strategy in the strategies view. When you replace the first with the word you want to search for, e.g., spel (game in Dutch), and the second with a user_id (e.g., Simone), the response will give you a result set of games that are relevant to Simone.

https://rest.sparque.ai/2.4/toys/q/COMMIT:_import:1485273642759/p/keyword/spel/p/user/Simone/results

The default format of the response message is JavaScript Object Notation (JSON), but it can also be requested in Extensible Markup Language (XML) format.

The response of the Sparque REST API contains a list of items. In the API endpoint, you can define the data type of these items. Typically, the data type is OBJ, an object from the database. However, it can also return a list of strings, for example for query suggestions, or a list of dates or integers. You can even return pairs in the response, for example an object with a date [OBJ,DATE].

A strategy queries the data in a specific way and with the input parameters provided by the API endpoint. To ensure that a strategy can be queried, the API endpoint must be defined, and the strategy must be assigned to this API endpoint. As part of the API endpoint definition, the relevant query input parameters are identified, as well as the data type of the input.

Click the button at the bottom right to create a new endpoint.

For an API endpoint, you must define at least an ID and a title. Specify a name and select the data type for each input parameter. For example, the API endpoint for Personalized Search contains the parameters keyword and user. Both parameters are of type String.

If you want to use a date in the strategy, you have to define this parameter in your endpoint as well. This parameter would be of type date.

In the same way, you can define the number and data type of what will be returned via the API.

To edit a strategy, use the API endpoint parameters. This is explained in the documentation of the editor.