Endpoint Configuration

• Item
• List
• Template
• Forward

Endpoints are the HTTP entry points which are accessible on your API. In sapi-nt, endpoints are designed to be RESTful whenever possible. A single endpoint is defined by its URL path, and may serve a variety of data in multiple formats.

Endpoint specs are characterised by the following type values:

You can define an endpoint whose name value is the value of the sapi-nt.api.defaultEndpointName application property to declare it as the default endpoint. If you do, requests that cannot be mapped to any particular endpoint will be directed to it.

Note

You can also declare time series endpoints which accept requests for data stored in a Cassandra database. Integrating sapi-nt with Cassandra is documented here.

URL paths

All endpoint specs have a url property, whose value is a URL path on which the endpoint is located. This path can be relative to the domain of your application, in which case it must start with the context path of the application. Otherwise, sapi-nt will infer that the path is relative to the context path. For example, if the context path is /api, then the endpoint url values /api/station and /station are equivalent.

You can define endpoints which accept requests to exact URL paths, or those matching a certain pattern. The variable parts of the path pattern are known as path parameters, and can be written as {pathParam}.

Path parameters which are written in this way will be treated as request parameters. For example, you can use this method to apply filter parameters to requests that target a certain endpoint, although this works the same way for any kind of request parameter. See the documentation for a full explanation of request parameters.

Example

To define an endpoint which reads a request parameter onLine from the requested URL, you can set the following url value in the endpoint spec:

url: /underground/{onLine}/station

When the path parameter is defined in this way, it must be handled by the sapi-nt application. If it is not an acceptable request parameter for that endpoint, sapi-nt will return a 400 Bad Request response.

However, you may need to define an endpoint which answers all requests matching a certain path pattern, but does not treat the path parameter as a request paramater. You can do this by prepending __ onto the path parameter in the endpoint spec’s URL path, eg. {__pathParam}. This indicates to sapi-nt that the parameter should not be treated as a request parameter, and it will be ignored.

This method is typically used to define item endpoints, which accept all requests with a certain path pattern, and return the resource whose URI corresponds to the full request URL.

Example

To define an item endpoint which returns resources whose URIs match a certain pattern, you can set the following url value in the endpoint spec:

type: endpoint.item
url: /underground/station/{__id}

Views

Item, list and template endpoints can define views, which are branching, tree-like structures that determine which property paths, relative to the root resources, will be exposed by the API.

Endpoint specs which support views can have the following properties:

An endpoint can have a single view (given by the view property of the endpoint spec), which will be applied to every request, or multiple views which the API user can select from by supplying a _view query parameter (given by the views property of the endpoint spec).

The value of the views property should be a nested map of key-view pairs. The keys identify each view in the context of the endpoint, and can be different from the name of the view itself. API users can request the view by setting the _view query parameter of their requests to that key.

The view which has the key default will be applied to any request that is handled by the endpoint which doesn’t specify a view.

The views can be written as a string, referring to the unique name of a view spec defined elsewhere in your application’s spec directory, or as inline view definitions, following the same YAML structure as described in the view spec documentation.

Example

A fragment of an endpoint spec with a default and a compact view, where the view spec compactView is defined elsewhere:

views :
  default :
    - "rdfs:label"
    - "skos:notation"
    - "eg:group"
    - prop : "skos:narrower"
      optional : true
      nested :
        - "rdfs:label"
        - "skos:notation"
        - "eg:group"
  compact : compactView
  detail:
    class: "def-pa:ProtectedArea"
    projection: "*,narrower.*,group.*"

Example

A fragment of an endpoint spec with a single view:

view :
  - "rdfs:label"
  - "skos:notation"
  - prop : "skos:narrower"
    optional : true
    nested :
      - "rdfs:label"
      - "skos:notation"

Batch Processing

If batch processing is enabled for your sapi-nt application, you can enable it for list and template endpoints by setting the enabled property on the nested batch property of the spec to true. See the documentation for how to configure individual endpoints.

Example

A fragment of an endpoint spec with batch processing enabled:

type: endpoint.list
batch:
  enabled: true

Documentation

Sapi-nt can be configured to automatically generate documentation for your API. See the documentation for how to use this feature. All endpoint specs can have the following documentary properties:

The nested documentary objects for path and query parameters can have the following properties:

Setting the required and pattern properties only affects the generated documentation does not necessarily mean that they will be enforced. You can enforce these rules on endpoints by configuring request validators.

Example

name      : station
type      : endpoint.item
url       : /underground/station/{__id}
description: "Details of a single station on the underground network."
example   : /underground/station/ActonTown
pathParameters:
  __id:
    description: ID of the station.
    type: xsd:string
    pattern: /([a-Z])*/

Endpoint Types

All endpoint specs have the standard name and type properties, as well as a url property (see above section on URL paths).

Item, list and template endpoints can all have the following properties:

Item

Item endpoints, having a type of endpoint.item, serve information about individual resources. Typically, a single item endpoint can emit all resources under a particular URL path.

An item endpoint spec can have the following properties:

You can configure the default values for some of these properties by setting the application properties under sapi-nt.defaults.spec.endpoint.item.

Example

name      : station.item
type      : endpoint.item
url       : /underground/station/{__id}
isDescribe: true

Describe Queries

Unlike other endpoints, item endpoints can perform SPARQL describe queries on resources by setting the isDescribe property to true. This is useful for exposing the main properties of a generic resource without having to define a specific view.

As such, it may be useful to set an item endpoint, with describe queries enabled, as the default endpoint for your API, since it will attempt to identify any request URI with the URI of a resource in the data set.

You can define an item endpoint with one or more views and describe queries enabled. This endpoint will handle requests by performing a describe query on every element of the view, and coalescing the resulting graph in the response.

Resource Location

When responding to a request sent to an item endpoint, sapi-nt uses the URL of the request and the base URI of the application to locate the corresponding resource. The resource URI is inferred by replacing the origin and context path of the requested URL with the base URI.

Example

For a sapi-nt application with a base URI of http://example.org/transport, a context path of /api, running on http://localhost:8080, with an item endpoint spec:

type: endpoint.item
url: /api/station/{__id}

A request sent to:

http://localhost:8080/api/station/ActonTown

Will attempt to return information about the resource with URI:

http://example.org/transport/station/ActonTown

List

List endpoints, having a type of endpoint.list, serve collections of resources, usually all belonging to a particular classification, such as having the same rdf:type or belonging to the same concept scheme.

A list endpoint spec can have the following properties:

You can configure the default values of some of these properties by setting the application properties under sapi-nt.defaults.spec.endpoint.list.

Sapi-nt dynamically generates the SPARQL queries that are issued by list endpoints, based on the structure of the associated view and the query parameters supplied by the request. As such, list endpoints are able to support many of the standard request parameters, including filters on property values. See the documentation for more information.

Example

name      : station
type      : endpoint.list
url       : /underground/station
query     : "?id a metro:UndergroundStation ."
textSearch: true
geoFilters:
  - CircleFilter
  - PolygonFilter
views :
  default :
    class: metro:UndergroundStation
    projection: "label,onLine(label),lat,long"
  compact : compactView
contentTypes:
  - "application/json"
  - "text/html"

Query Configuration

The query property on a list endpoint spec determines the base query for locating the root resources associated with the endpoint. It can be provided as a fragment of a SPARQL WHERE clause, using the variable ?id to denote the root binding, or as a nested configuration object.

When a nested configuration object is given, its key-value pairs denote a set of filters to apply to the data set. The keys denote the RDF properties to which to apply the filter, and the corresponding values are the values to filter on. Keys should be given as full or compact URIs (using the prefix mapping defined in the default model). Values can also be given as compact URIs in the same way. Their type will be inferred automatically.

Since it is often necessary to define this base query as a filter on rdf:type, you can simply use the key type to denote rdf:type.

Both SPARQL fragments and the property values of nested configuration objects can use a variable binding syntax, ${variable} to denote that the value should be taken from the request parameter with the same name. If any variables in a query definition are not bound by the request, the request will fail with a 400 Bad Request response.

Example

A list endpoint spec with a raw SPARQL query definition:

name      : listQueryFragment
type      : endpoint.list
url       : /example/path
query     : "?id a skos:Concept ."

Example

A list endpoint spec with a nested query definition:

name      : listQueryConfig
type      : endpoint.list
url       : /example/path
query     :
  type: "skos:Concept"

Text Search Configuration

The textSearch property on an list endpoint spec determines whether users will be able to request a search on the Lucene text index of the underlying store. See the request parameters documentation for more detail.

The textSearch configuration can be given in the following forms:

If any form is given except for false, then text search will be enabled.

The nested configuration object can have the following properties:

The fuzzy property can given as a nested object with the following properties:

See the Lucene documentation for more information about fuzzy search options.

Example

name      : listTest
type      : endpoint.list
url       : /test/path
query     : "?id a skos:Concept ."
textSearch:
  root: id
  fuzzy:
    enabled: true
    similarity: 0.7
  limit: 50000

Template

Template endpoints, having a type of endpoint.template, serve the results of specific parameterised SPARQL queries. You can use them to issue queries which don’t conform to the dynamically generated structure of list endpoints, such as aggregation queries. However, this means that many standard request parameters such as filters and text searches are not supported by template endpoints.

The template for the SPARQL query issued by a template endpoint is given by the query property of the spec. Unlike list endpoints, this must be a complete and valid SPARQL query, including namespace prefix mappings.

Similarly to list endpoints, template queries can contain bindable variables, denoted by %{variable}, which will take values from the request parameters of the same name. If any variables in a template query are not bound by the request, the request will fail with a 400 Bad Request response.

A template endpoint spec can have the following properties:

Forward

Forward endpoints, having a type of endpoint.forward, delegate requests to other endpoints. Forward endpoints are unique in that they don’t define any behaviour of their own, but simply provide alternative access points to other endpoints.

However, the main usage of forward endpoints is to supply request parameters given by their URL paths to other endpoints, since path parameters are retained on the request handled by the delegated endpoint. For example, you can create a forward endpoint which entails a filter parameter on another endpoint.

A forward endpoint spec can have the following properties:

Example

To define a forward endpoint that supplies the onLine filter parameter to a list endpoint named station, you can use the following specs:

type: endpoint.list
name: station
url: /underground/station
view:
  - prop: rdfs:label
  - prop: metro:onLine
    name: onLine
    valueBase: "lu-l:":
---
type: endpoint.forward
name: station.line
url: /underground/{onLine}/station
forwardTo: station