Query API¶

The Query API is used to retrieve answers to search queries. This section walks you through understanding and using the Query API, a must when developing your own applications on top of Spinque.

Basics of the Query API¶

The Query API is fully stateless. Making the same request twice will yield the same result twice. This also means that every request that is made of the Query API must contain all relevant information for the execution of that request.

All requests made of the Query API use the HTTP GET request method.

A request URL is constructed out of 4 parts:

root

the base of the search application.

query

the part of the request that specifies the query you want an answer to.

response type

defines what response you expect: a page of results, the facet options, or statistics about the query.

options

optional modifiers such as count, offset, or cutoff.

Request root¶

All requests have a root of the following form:

GET https://rest.spinque.com/<name>/¶

Where <name> is the name of your workspace.

A workspace is the environment within Spinque Desk in which users create datasets, pipelines, strategies, APIs, testsets.

Query¶

Endpoints¶

In Spinque Desk, users can expose strategies through the Query API as endpoints. These endpoints are grouped together in an API. APIs and endpoints belong to a workspace and have their own names.

The query part of a request specifies which API and endpoint(s) to use along with values for their parameters:

GET /api/<api>/e/<endpoint>/p/<name>/<value>¶

Where <api> is the name of the API (preceded by ‘/api/’), <endpoint> is the name of the endpoint (preceded by ‘/e/’ for endpoint), <name> is the name of the the parameter (preceded by ‘/p/’ for parameter) and <value> is its value.

Example request

GET /api/portal/e/search/p/topic/john/¶

Parameters¶

The parameters that can be filled are defined by the endpoint. Sign in to Spinque Desk to view the exposed APIs and endpoints.

An endpoint can have 0 to many parameters. Filling multiple parameters using the Query API is done by simply appending them:

GET /api/<api>/e/<endpoint>/p/<name1>/<value1>/p/<name2>/<value2>¶

The order in which the set of parameters is given is not relevant. Specifying the same parameters multiple times with different values is not allowed, and the result is not defined in such cases.

Example request

GET /api/portal/e/search/p/topic/utrecht/p/color/purple¶

Stacking endpoints¶

Some endpoints take the result of another endpoint as input. These are called stackable endpoints and can be used as follows:

GET /e/<endpoint1>/p/<name1>/<value1>/e/<endpoint2>/p/<name2>/<value2>¶

Where <endpoint1> is the name of the first endpoint, <name1> is the name of a parameter of the first endpoint, <value1> is its value, <endpoint2> is the name of the endpoint that receives the result of the first endpoint as input, <name2> is the name of a parameter of this second endpoint and <value2> is its value.

The stacking of more than one endpoint is supported.

Faceted search¶

Using endpoint stacking, faceted search can be implemented with Spinque.

Three endpoints are involved with one facet: the search endpoint (that retrieves results), the facet options endpoint (that retrieves all options the facet should show) and the facet filter endpoint (that filters down the results based on the selected options). As a naming convention, facet filter endpoints are often appended with :FILTER to help disambiguate the options and filter endpoints. The parameter with selected values is often named ‘value’ and often expects the value to be in tuple notation

Example requests

GET /api/portal/e/search/p/topic/jan/e/birthplaces¶

To get all options to display in the facet. In this case, it shows all birthplaces of the items found when searching for ‘jan’.

GET /api/portal/e/search/p/topic/jan/e/birthplaces:FILTER/p/value/1.0("Utrecht")¶

To show filtered search results when an option (‘Utrecht’) has been selected.

Context parameters¶

Context parameters hold for all further query endpoints in the URL. They can be specified at any location in the URL (even before the first query endpoint):

GET /c/<name>/<value>¶

Example request

GET /api/portal/c/language/NL/e/search/p/topic/utrecht/¶

Response Type¶

The end of the URL path specifies the response type you expect. This can be: results or statistics.

GET /e/<endpoint>/.../results¶

Provides a list of results, sorted on probability.

Example request

GET /api/portal/e/search/p/topic/utrecht/results¶

Example response

{
  "offset": 0,
  "count": 10,
  "type": [
      "OBJ"
  ],
  "items": [
    {
      "rank": 1,
      "probability": 1.0,
      "tuple": [
        {
          "id": "...",
          "class": [
            "..."
          ],
          "attributes": {
            "name": "..."
          }
        }
      ]
    }
  ]
}

GET /e/<endpoint>/.../statistics¶

Provides information about the number of matches, and information about the distribution of probabilities in the result set.

Example request

GET /api/portal/e/search/p/topic/utrecht/statistics¶

Example response

{
  "total": 30999,
  "stats": [
    {
      "cutoff": "0.1",
      "numResults": 10
    },
    {
      "cutoff": "0.01",
      "numResults": 5362
    },
    {
      "cutoff": "0.001",
      "numResults": 25627
    }
  ]
}

Request options¶

The following options can be added to the URL query string:

config

Name of the configuration to use. Dafault value is ‘default’ (the initial configuration of a workspace).

When using the results response type, these additional options are available:

count

Number of items returned. Default value is 10. Should be between 1 and 100.

offset

Offset on the number of items returned. Default is 0. Should be 0 or more.

format

Formatting of the results: json/xml/rdf/csv/xlsx. Default value is ‘json’. Note: XML is not enabled by default, and RDF can only be requested when ouput of strategy is [STRING,STRING,STRING]

level

Level of the result descriptions. Default value is 1. Should be 0 or more.

homogeneousArrays

boolean option to specify whether items in a result-tuple are returned as an array (false) or as an object (true). This option was introduced because some programming environments struggle with arrays that contain heterogeneous items (mix of strings, numbers, arrays, objects).