Query API

In Sparque 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 parameter (preceded by '/p/' for parameter) and <value> is its value.

Example request

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

The parameters that can be filled are defined by the endpoint. Sign in to Sparque 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

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.

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

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/

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
    }
  ]
}