Predefined query endpoint (beta)

Since 4.1.0.

The predefined query endpoint enables the specification of custom low-latency Web APIs in a declarative manner. It relies on two main components:

1. A JSON-based configuration file, describing the API interface, its parameters and optionally a JSON-LD frame (opens new window) for shaping the returned data.
2. A SPARQL query in charge of retrieving and perhaps transforming the data. The values of the API parameters are plugged as constants into the SPARQL query.

WARNING

At the moment only CONSTRUCT queries are supported.

This endpoint brings one important benefit in terms of performance with respect to the SPARQL endpoint: it is able to reuse reformulations from similar queries. This is particularly valuable for "lookup" requests involving many optional triples, and for which latency is critical.

This endpoint can be deployed using the command ontop endpoint or the Docker image ontop/ontop (opens new window).

HTTP API

GET /predefined/{queryId}?{param1}={value1}&{param2}={value2}&{param3}={value3}

Example

Configuration

{
    "queries": {
        "lodging": {
            "queryType": "graph",
            "name": "Lodging businesses",
            "description": "JSON-LD snippets for lodging businesses, based on schema.org.",
            "return404IfEmpty": true,
            "resultStreaming": false,
            "parameters": {
                "id": {
                    "description": "Internal identifier of the lodging business",
                    "type": "xsd:string",
                    "safeForRandomGeneration": true,
                    "required": true
                },
                "language": {
                    "description": "Language (e.g. it, de, en, ru). Default: en",
                    "type": "xsd:string",
                    "safeForRandomGeneration": false,
                    "required": false
                }
            },
            "frame": {
                "@context": "https://schema.org",
                "@type": [
                  "LodgingBusiness"
                ]
            }
        }
    }
}

Predefined queries

[lodging]
query="""
BASE <http://noi.example.org/data/accommodation/>
PREFIX schema: <http://schema.org/>
PREFIX : <http://noi.example.org/ontology/odh#>
 CONSTRUCT {
   ?h a schema:LodgingBusiness ; schema:name ?nameStr ; schema:priceRange ?priceRange .
 }
 WHERE {
  # Convert incoming parameters
  BIND (IRI(?id) AS ?h)
  BIND (COALESCE(?language, "en") AS ?l)
  ?h a schema:LodgingBusiness .
  OPTIONAL { 
    ?h schema:name ?name .
    BIND(str(?name) AS ?nameStr)
    FILTER(lang(?name) = ?l)
  }
  OPTIONAL {
    ?h schema:priceRange ?priceRange .
  }
}
"""

Cache for the JSON-LD contexts

Optionally, JSON-LD context documents can be stored in a cache and adapted if needed. When they are not cached, these documents are directly fetched from the Web.

{
  "https://schema.org": {
    "@context": {
      "@vocab": "http://schema.org/"
    }
  }
}

Request

curl http://localhost:8080/predefined/lodging?id=32E7BE648E7B11D181AB006097B896BA&language=de

Results:

{
  "@context": "https://schema.org",
  "@id": "http://noi.example.org/data/accommodation/32E7BE648E7B11D181AB006097B896BA",
  "@type": "LodgingBusiness",
  "name": "Alpenblick - Gasthaus"
}

Entries

Top-level key

Key	Type	Description
queries	Map of predefined queries	Groups predefined queries by id.

Query keys

Key	Type	Description
queryType	String	At the moment, only graph is supported. Corresponds to CONSTRUCT queries.
name	String	Name of the predefined query.
description	String	Description of the predefined query.
return404IfEmpty	Boolean	If true, returns a 404 status code when the result set is empty.
resultStreaming	Boolean	If true, uses the chunked transfer encoding.
parameters	Map of parameters	Groups parameters by id.
frame	JSON object	JSON-LD frame (opens new window)) for shaping the result set when the JSON-LD format is selected.

Parameter keys

Key	Type	Description
description	String	Description of the parameter.
type	String	Type of the parameter. Can be iri for an IRI, any XSD datatype like xsd:string with the prefix xsd: or the IRI string of an RDF datatype.
safeForRandomGeneration	Boolean	If true, replacing the parameter value by a random value for generating a "reference" reformulated query can be considered as safe. Replacing afterwards the random value but the real parameter value in the reference reformulated query should produce the expected result. Usually, identifiers are safe while languages are not because the columns to consider differ from a language to another.
required	Boolean	If true, a value must be given for this parameter in the HTTP request.