Endpoint Configuration

• Item
• List
• Template
• Forward
• Time Series
• Hierarchy

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, template and hierarchy endpoints can all have the following properties:

Aliases

Each endpoint can configure a mapping of parameter aliases to the names of the parameters they represent. You can set this by setting the aliases property on the endpoint spec. This allows users to send the aliased parameters either in their original form, or using an alias. This may be useful for shortening the names of commonly used filter parameters, for example.

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.

Item Views

Item endpoints can support views in the same way as list endpoints.

If an item endpoint has a view and uses describe queries, it will return a description of every element of the view.

Note that such endpoints also support projections using the _projection request parameter. If you request a specific projection on an endpoint that uses a describe query, it will use a select query instead.

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.

See the geospatial filtering document for more information about how to configure the geoFilters and geoParameter properties.

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. To query resources of both a type and its sub-types, use the superType key. Note that to resolve sub-types, the dataset must contain a description of the class hierarchy.

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 documentation for more information about how to use the text search API.

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

Time Series

You can configure an endpoint which emits time series data from a tabular data source.

See the relevant documentation for these database integrations:

• Cassandra
• PostgreSQL

Time series endpoint specs have a type value of timeseries and can have the following properties, in addition to the properties usually allowed on list endpoint specs:

• Note that timestampTimeParam value is expected to match the HH:MM:SS pattern and it will query the rows that match the timestamp column time part regardless of date.

When using a PostgreSQL data source, you do not need to specify byDateTable as all queries will select rows from the byMeasureTable.

The indexed columns, given by indexCols, are used to validate queries sent to SQL data sources to ensure that the query performance will be acceptable. In particular, requests can only sort on indexed columns, and can only filter on sets of properties that include at least one indexed column.

Hierarchy

You can configure an endpoint which emits hierarchical data from a SPARQL data source. Each hierarchy endpoint serves the item and list descriptions of a specific hierarchy scheme (eg. a skos:ConceptScheme) and its members (eg. skos:Concepts).

See the documentation more information about how to use the hierarchy API.

To define a hierarchy endpoint spec, set the type of the spec to endpoint.hierarchy. Hierarchy endpoint specs have the following configurable properties:

Example

name: region.hierarchy
type: endpoint.hierarchy
url: "/region"
scheme: "egc:Region"
relation: skos
locator: hierarchy
list:
  view:
    class: "skos:Concept"
    projection: "*"

Relations

The members of the hierarchy must relate to each other, and to the hierarchy scheme itself, in a determined way in order for the hierarchy API features to work.

The relation property on your endpoint spec should be a nested object with the following properties:

Each relation should be written as a property URI or CURI (using the prefix mapping from the default model).

When both a relation and its inverse (eg. parent and child) are specified, sapi-nt will treat the relation as the disjunction of the relation property with the inverse of its inverse property.

Alternatively, you can use a preset set of relations, based on the SKOS ontology, by setting the value of the relation property to skos. The preset has the following relations:

Locators

The choice of locator (uri or hierarchy) determines how sapi-nt maps hierarchy API requests to resources.

The root path specified by the url property on the endpoint spec always maps to the hierarchy scheme. In addition, with the default uri locator, any path that extends the root path will map to the resource whose URI is the corresponding extension of the scheme URI.

For example, for a scheme:

http://example.org/region

whose endpoint is located at:

/api/example

the path:

/api/example/uk/england

would map to the hierarchy member:

http://example.org/region/uk/england

if it exists.

However, if the URIs of members of the hierarchy do not extend the scheme URI, you should use the hierarchy locator configuration. This locator identifies the path segments of the request with the identifiers of a series of related members. The identifiers for each hierarchy member are inferred from the configured id relation.

For example, with the scheme and endpoint path described above, the path:

/api/example/uk/england

would map to the hierarchy member whose identifier is england, and whose parent (given by the parent relation) is a root member with the identifier uk. As such, member identifiers must be unique among their siblings in the hierarchy.

Lists

When a user requests a list of hierarchy members, the returned description can be configured by the list configuration. The list property on a hierarchy endpoint spec should be a nested object with the following properties.

All of the properties have the same effects and default values as those on list endpoints.