APIs¶
When you are satisfied with how your strategies work, you connect them to your application via an API. An API contains endpoints for all the strategies you created to make your application work. You create and manage your APIs in this section of Spinque Desk.
Endpoints¶
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 Spinque Desk. The Spinque REST API (Representational state transfer Application Programming Interface) is used to define the request messages as well as the type of response messages.
In the screenshot below you see the API endpoints that are defined for an example 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 and two endpoints that power a genre facet.
Structure of the Spinque REST API¶
The request URL consists of a number of 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. In this URL …
https://rest.spinque.com/2.5/{WORKSPACE}/api/e/{ENDPOINT}/p/keyword/{STRING}/p/user-id/{STRING}/results
* **rest.spinque.com** represents the domain.
* **2.5 represents the _used version_ of Spinque Desk.
* **/{WORKSPACE}** represents the _workspace_ where the data resides.
* **/{ENDPOINT}** represents the endpoint that queries the data.
* **/p/keyword/{STRING}** represents the parameter _keyword_, 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 parameter _user_, 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 strategy that is queried is identified by a unique commit_id. This commit_id is shown for each committed strategy in the strategies view. When you replace the first {STRING} 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 with games that are relevant for Simone.
https://rest.spinque.com/2.4/toys/q/COMMIT:_import:1485273642759/p/keyword/spel/p/user/Simone/results
See the documentation of the REST API for more details.
Output¶
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 Spinque REST API contains a list of items. In the API endpoint you define the data type of these items. Typically the data type is OBJ, an object from the database. But 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].
Creating a Spinque REST API¶
A strategy queries the data in a specific way and with the input parameters provided via the API endpoint. To ensure a strategy can be queried, the API endpoint needs to be defined and the strategy needs to be assigned to this API endpoint. As part of defining the API endpoint, the relevant query input parameters are identified as well as what data type the input will be.
Click the button at the bottom right to create a new endpoint.
For an API endpoint you have define at least an id and a title. For each input parameter you provide a name and select the data type. For example, the API endpoint for Personalized Search contains the parameters keyword and user. Both parameters are of type String.
If you would want to use also a data 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 define the number and data type of what is returned via the API.
Using an API endpoint in the editor¶
When you edit a strategy you use the parameters of the API endpoint. This is explained in the documentation of the editor.