Endpoint configuration

An API comprises a set of endpoints (which may be list or item endpoints). These are configured through a mix of JAX RS resource classes and configuration files.

The configuration files define the main attributes of an endpoint:

• type
• associated query
• views defining a projection of the matching resources to return (required for list endpoints but optional for item endpoints)
• optional additional constraints such as soft/hard result length limit

The binding of an endpoint to a specific URL pattern can be done through a JAX RS resource or by means of a url attribute within the configuration file. The ability to define the binding in configuration files makes it possible to dynamically add endpoints and to reuse a single API war for multiple configurations (in a similar style to Elda). The ability to perform the binding in code makes it possible to customize the API by transforming the request parameters, or query.

Configuration area

The appbase configuration defines an area from which configuration files can be (dynamically) loaded. This can be defined as some external configuration point or can reference a folder within the war. During development the dynamic loading allows modification of configuration files within the war without having to restart a container.

The configuration files can be JSON or YAML, for YAML then multiple "documents" in one file are supported.

A configuration document can define a single endpoint or a named view (ViewMap) which can then be reused across endpoints.

Endpoint configuration file

An endpoint specification is a JSON object with the following fields:

Name	Purpose
name	Identifier for the endpoint can be used for programmatic look up
type	Either list or item
prefixes	Optional set of prefix/URI bindings which are in addition to the global prefix set defined in the API configuration. The value of this field should be a JSON object where the field name is the prefix and the value is a string giving the URI expansion of that prefix
url	URL of the endpoint, relative to base context. Not relevant/needed for programmatic endpoints. Can include {arg} patterns which will match to path parameters which will be available as filters. To avoid such filtering use {__arg}
baseQuery	For SPARQL-based list endpoints this is a fragment of a SPARQL query that binds ?id to the desired matching resources
query	A complete SPARQL query which can contain injection points $_graphPattern $_graphPatternEarly $_graphPatternLater $_sort $_modifiers. Not needed if the query is defined by the view.
view	Defines the default view, either a string identifying a view defined elsewhere or an in-line view specification, equivalent to specifying a view called default within the views object
views	A JSON object which maps view names (which can be requested with the _view parameter) to view specifications (which in turn may be identifiers or in-line), optional
limit	Optional hard limit on the maximum number of results that can be returned from this endpoint
softLimit	Optional default limit on the number of results that can be returned for use when the query does not specify a limit.
template	Name of a velocity template to use to render results to HTML
textSearch	Optional setting for text search. Can be a boolean (where false means no text search on this endpoint) or a string giving the variable to search on (using when filtering on associated resources instead of the root). Requires the SearchRequestProcessor to be configured in order to take effect.
geoSearch	Optional setting for geo search. Can be a boolean (where true defaults to a withinBox search of the root resource) or an object with fields parameter (the variable to search on, default is id) and algorithm (the geo filter algorithm to use, default is withinBox). Requires the GeoRequestProcessor to be configured to in order to take effect.
itemName	Optional name for the type which can be used in documentation templates. Useful for things like rdfs:label which can come up multiple times in the same view so the documentation can say "the label of the foo" instead of the "the label of the item"
distinct	Set to true to add a DISTINCT qualifier to the query (or the inner query if this uses nested selects)
nestedSelect	Set to true to wrap the base query in a inner select to which limit/offsets will be applied. Useful if the query can return multiple rows for the same ?id binding.
nestedSelectVars	A string or list of strings each of which is a variable name to be projected out of the nestedSelect (in addition to the default ?id). Only needed in special cases. For example when a geo query needs return a distance parameter this is typically done as part of the inner select. Do not include the ? in the name.
suppressID	Set to true to cause CSV (or similar) serializations to omit the root resource URI. Useful for things like measurements where you typically just want to the time/value/measure not an ID for each row.

View specification

A view defines a tree-shaped projection of those properties and values to be extracted from resources that match the query.

A view is encoded using an array of entries, each of which specifies an RDF property, its corresponding name in JSON/CSV serializations and some optional metadata.

The simplest entry is a string given the RDF Property (normally in prefixed form). In this case the corresponding JSON name will be the localname part of the property.

The alternative entry is a JSON object with the following fields:

Name	Meaning	Default
prop	The RDF property, normally in prefixed form
name	Shortname to use in serializations and queries	localname of the property
optional	Boolean flag to indicate the property is optional within the view	false
multi	Indicates the property is multivalued and should be returned as an array even if there is no value or a single value present	false
filterable	Indicates the property may be referred to in filter expressions	true
type	The datatype for values of this property, normally in prefixed form, can be rdf:PlainLiteral or rdfs:Resource as well as xsd:xxx	Otherwise the value's type is inferred from syntax as being one of string, number, dateTime or date
comment	Descriptive comment for the property used in generated documentation, not needed if this is already given in a matching ontology but can be useful to explain view-specific aspects
nested	Indicates that the value of this property will be a resource and defines a sub-view to be applied to that resource.
valueBase	Provides a base URI that allows properties of type Resource to be filtered by localname only
hide	If set to true then this value will be omitted from CSV output, useful when rendering nested objects to produce simpler CSVs (legacy alias for this suppressID is still supported)

Example

Putting these together an example endpoint specification is:

name      : listTest2
type      : list
query     : "?id a skos:Concept ."
views :
  default :
    - "rdfs:label"
    - "skos:notation"
    - "eg:group"
    - prop : "skos:narrower"
      optional : true
      nested :
        - "rdfs:label"
        - "skos:notation"
        - "eg:group"
  compact : compactView

This defines a single endpoint with two views a default one (given inline) and a compact one (given by some other view specification file). The default view has four top level properties, one of which (skos:narrower) is optional expands to a nested view.

View file

As well as defining views in-line in an endpoint specification then a reusable named view can be given in a separate file (or separate JSON document within the same YAML file). For example:

name: compactView
type: view
view :
    - "rdfs:label"
    - "skos:notation"
    - "eg:group"