OGC API

Each API represents a deployment of a single OGC Web API, i.e., an API that implements conformance classes from OGC API standards.

General rules

Response encoding

For operations that return a response, the encoding is chosen using standard HTTP content negotiation with Accept headers.

GET operations that support more than one encoding additionally support the query parameter f, which allows to explicitly choose the encoding and override the result of the content negotiation. The supported encodings depend on the affected resource and the configuration.

Response language

For operations that return a response, the language for linguistic texts is chosen using standard HTTP content negiotiation with Accept-Language headers.

If enabled in Common Core, GET operations additionally support the query parameter lang, which allows to explicitely choose the language and override the result of the content negotiation. The supported languages depend on the affected resource and the configuration. Support for multilingualism is currently limited. There are four possible sources for linguistic texts:

• Static texts: For example link labels or static texts in HTML represenations. Currently the languages English (en) and German (de) are supported.
• Texts contained in the data: Currently not supported.
• Texts set in the configuration: Currently not supported.
• Error messages: These are always in english, the messages are currently hard-coded.

Resource paths

All resource paths in this documentation are relative to the base URI of the API. For example given the base URI https://example.com/pfad/zu/apis/{apiId} and the relative resource path collections, the full path would be https://example.com/pfad/zu/apis/{apiId}/collections.

Configuration

Details regarding the API modules can be found here, see api in the table below.

Name	Default	Description	Type	Since
id		Unique identifier of the entity, has to match the filename. Allowed characters are (A-Z, a-z), numbers (0-9), underscore and hyphen.	string	v2.0
label	{id}	Human readable label.	string	v2.0
description	""	Human readable description.	string	v2.0
enabled	true	Option to disable the service, which means its REST API will not be available and background tasks will not be running.	boolean	v2.0
shouldStart	true	Deprecated See enabled.	boolean	v2.0
apiVersion	null	Adds a version to the URL path, instead of /{id} it will be /{id}/v{apiVersion}.	number	v2.0
auto	false	Option to generate missing definitions automatically from the data source.	boolean	v2.0
autoPersist	false	Deprecated, use the editor instead. Option to persist definitions generated with auto to the configuration file. The Store must not be READ_ONLY for this to take effect.	boolean	v2.0
serviceType	OGC_API	Always OGC_API.	string	v2.0
metadata	{}	General Metadata for the API.	object	v2.0
externalDocs	{}	Link to a document or website with more information about this API.	object	v2.1
defaultExtent	{ "spatialComputed": true, "temporalComputed": true }	By default, the spatial and temporal extent of data is derived from the data when starting the API, but the Default Extent can also be configured.	object	v2.0
defaultCaching	{}	Sets fixed values for HTTP Caching Headers for the resources.	object	v3.1
accessControl	{}	Access Control configuration.	object	v3.3
apiValidation	NONE	During startup of an API, the configuration can be validated. The supported values are NONE, LAX, and STRICT. STRICT will block the start of an API with warnings, while an API with warnings, but no errors will start with LAX. If the value is set to NONE, no validation will occur. Warnings are issued for problems in the configuration that can affect the use of the API while errors are issued for cases where the API cannot be used. Typically, API validation during startup will only be used in development and testing environments since the API validating results in a slower startup time and should not be necessary in production environments.	string	v2.1
tags	[]	Tags for this API. Every tag is a string without white space. Tags are shown in the API Catalog and can be used to filter the catalog response with the query parameter tags, e.g. tags=INSPIRE.	array	v2.1
api	[]	API Building Blocks configuration.	array	v2.0
collections	{}	Collection configurations, the key is the collection id, for the value see Collection below.	object	v2.0

Collection

Every collection corresponds to a feature type defined in the feature provider (only Feature Collections are currently supported).

Name	Default	Description	Type	Since
id		Unique identifier, allowed characters are (A-Z, a-z), numbers (0-9), underscore and hyphen.	string	v2.0
label	{id}	Human readable label.	string	v2.0
description	""	Human readable description.	string	v2.0
enabled	true	Enable the collection?	boolean	v2.0
persistentUriTemplate	null	The Feature resource defines a unique URI for every feature, but this URI is only stable as long as the API URI stays the same. For use cases where external persistent feature URIs, which redirect to the current API URI, are used, this option allows to use such URIs as canonical URI of every feature. To enable this option, provide an URI template where {{value}} is replaced with the feature id.	string	v2.0
additionalLinks	[]	Array of additional link objects, required keys are href (the URI), label and rel (the relation).	array	v2.0
api	[]	Building Blocks configuration.	array	v2.0
capabilities	[]	Deprecated See api.	array	v2.0

Building Blocks

Building blocks might be configured for the API or for single collections. The final configuration is formed by merging the following sources in this order:

• The building block defaults, see Building Blocks.
• Optional deployment defaults in the defaults directory.
• API level configuration.
• Collection level configuration.
• Optional deployment overrides in the overrides directory.

Metadata

General metadata for the API (version, contact details, license information). Supported keys with affected resources:

• version: API Definition,
• contactName: API Definition, HTML Landing Page
• contactUrl: API Definition, HTML Landing Page
• contactEmail: API Definition, HTML Landing Page
• contactPhone: HTML Landing Page,
• licenseName: API Definition, HTML Landing Page, Feature Collections, Feature Collection
• licenseUrl: API Definition, HTML Landing Page, Feature Collections, Feature Collection
• keywords: HTML meta tages and schema:Dataset in HTML Landing Page
• attribution: Landing Page, maps
• creatorName: schema:Dataset in HTML
• creatorUrl: schema:Dataset in HTML
• creatorLogoUrl: schema:Dataset in HTML
• publisherName: schema:Dataset in HTML
• publisherUrl: schema:Dataset in HTML
• publisherLogoUrl: schema:Dataset in HTML

All values are strings, except keywords, which is an array of strings.

Name	Default	Description	Type	Since
contactName		Optional name of a contact person or organization for the API.	string	v2.0
contactUrl		Optional URL of a contact webpage for the API.	string	v2.0
contactEmail		Optional email address for information about the API.	string	v2.0
contactPhone		Optional phone number for information about the API.	string	v2.0
creatorName		Optional name of a creator of data shared via the API.	string	v3.0
creatorUrl		Optional URL of a website of the creator of data shared via the API.	string	v3.0
creatorLogoUrl		Optional URL of a logo bitmap image of the creator of data shared via the API.	string	v3.0
publisherName		Optional name of the publisher of this API.	string	v3.0
publisherUrl		Optional URL of a website of the publisher of this API.	string	v3.0
publisherLogoUrl		Optional URL of a logo bitmap image of the publisher of this API.	string	v3.0
licenseName		Name of the license of the data shared via this API.	string	v2.0
licenseUrl		URL of the license of the data shared via this API.	string	v2.0
keywords		Keywords describing this API.	array	v2.0
version	1.0.0	Version for this API in the OpenAPI definition.	string	v2.0
attribution		Attribution text for data shared via this API, e.g., for display in maps.	string	v3.0

External document

External document with additional information about this API, the url key is required, the description key is recommended.

Name	Default	Description	Type	Since
description		Description of the content of the document or website.	string	v2.1
url		URL of the document or website.	string	v2.1

Default extent

By default, spatial and temporal extents of the collections are derived from the data during startup. The extent of the dataset is always the union of the collection extents. For large datasets the automated derivation will slow down the startup of the API.

If the spatial extent should not be derived from the data source on startup, set spatialComputed to false.

If the temporal extent should not be derived from the data source on startup, set temporalComputed to false.

As an alternative, a default value for the spatial (spatial) and/or temporal (temporal) extent for each collection can be set.

• Required keys for spatial extents (all values in CRS84): xmin (western longitude), ymin (southern latitude), xmax (eastern longitude), ymax (northern latitude).
• Required keys for temporal extents (all values in milliseconds since 1 January 1970): start, end.

Name	Default	Description	Type	Since
spatial		West- and east-bound longitude (xmin, xmax), south- and north-bound latitude (ymin, ymax) of the data. Optionally, minimum and maximum elevation (zmin, zmax) can be provided, too.	object	v2.0
spatialComputed	true	The spatial extent of each collection is automatically dervied from the data during the startup of the API. If the collection has no temporal properties, the collection will not have a temporal extent.	boolean	v2.0
temporal		start and end of the temporal extent of the data, specified as a RFC 3339 string in UTC. Unspecified values indicate an unbounded interval end.	object	v2.0
temporalComputed	true	The temporal extent of each collection is automatically dervied from the data during the startup of the API. If the collection has no temporal properties, the collection will not have a temporal extent.	boolean	v2.0

Caching

The following HTTP headers for HTTP caching are set in responses - as far as they can be determined for the respective resource:

• Last-Modified: The timestamp of the last modification is determined - if possible -
  from the representation of the resource to be returned, e.g. from the modification date of a
  file. It can be overridden via a configuration setting (see below).
• ETag: The tag is
  determined - if possible - from the representation of the resource to be returned.
• Cache-Control: The header is only set if it has been configured for the module's resources
  (see below).
• Expires: The header is set only if it has been configured for the module's
  resources (see below).

In any module that provides resources and does not just implement query parameters or output formats, there is a caching configuration option whose value is an object with the following optional entries.

Name	Default	Description	Type	Since
lastModified	null	For the resources in the building block, the Last-Modified header is set to the configured value. The value overrides any modification time determined from the resource.	string	v3.1
expires	null	For the resources in the building block, the Expires header is set to the configured value.	string	v3.1
cacheControl	null	For the resources in the building block, the Cache-Control header is set to the configured value. Exception are the Features and Feature resources, where cacheControlItems is to be used.	string	v3.1
cacheControlItems	null	For the Features und Feature resources in the building block, the Cache-Control header is set to the configured value.	string	v3.1

Access Control

Access control for all API operations (combination of endpoint and HTTP method).

Permissions

Access control is based on permissions and permission groups.

Permissions are a combination of a group prefix (see below) and an OpenAPI operation id (without any prefix), for example data:getItems or tiles:getTile. These can be used if a more fine-grained control is needed in comparison to permission groups.

Permission groups

These are the predefined main permission groups, every operation/permission is contained in exactly one main group:

• discover: access API landing pages, conformance declarations and OpenAPI definitions
• collections:read: access feature collection metadata
• data:read: access and query features
• data:write: mutate features
• tiles:read: access tiles
• styles:read: access styles and their metadata
• styles:write: mutate styles and update their metadata
• resources:read: access file resources
• resources:write: mutate file resources
• search:read: access stored queries and their parameters
• search:write: mutate stored queries
• routes:read: access stored routes and their definition
• routes:write: compute and store routes, delete stored routes

These are the predefined parent permission groups (convenient unions of main groups):

• collections: includes collections:read
• data: includes data:read and data:write
• tiles: includes tiles:read
• styles: includes styles:read and styles:write
• resources: includes resources:read and resources:write
• search: includes search:read and search:write
• routes: includes routes:read and routes:write

These are the predefined base permission groups (convenient unions of main groups):

• read: includes discover, collections:read, data:read, tiles:read, styles:read, resources:read, search:read and routes:read
• write: includes data:write, styles:write, resources:write, search:write and routes:write

Custom permission groups are defined in groups, they may contain permissions and/or predefined permission groups.

The special permission group public defines the list of permissions and/or predefined permission groups that every user possesses, if authenticated or not.

Data-specific permissions

The permissions groups and permissions described above will permit access to any API and collection. To restrict the access to specific APIs or collections, a suffix can be added to permission groups and permissions, for example read::daraa or data:getItems::daraa:AeronauticSrf.

Scopes

OAuth2 Scopes are an optional additional authorization layer. They are typically used when access to an API is granted to a third-party application on behalf of a user. Scopes then allow to limit which of the users permissions should be granted to the application. The application would request the scopes it needs and the user would be presented a consent form where he can choose the scopes he wishes to grant.

Scopes are disabled by default and can be enabled by setting the scopes option. The value is a list of the permission group types that should be used as scopes. That allows to set the granularity of scopes, since presenting too many scopes in a consent form might be overwhelming and all the enabled scopes have to actually exist in the identity provider.

For example setting scopes to [BASIC] would enable the scopes read and write. When a user then grants the write scope to an application, that does not automatically mean the application is allowed to write anything. What the application can write is still defined by the users permissions. But not granting the write scope is an easy way to prohibit any write access, even if the user has such permissions.

Authentication and authorization

To support authenticated users, a bearer token has to be included in the Authorization header in requests to the API. Validation and evaluation of these tokens has to be configured in the global configuration.

To determine if a user is authorized to perform the requested operation, the following steps are executed:

1. If the operation is covered by the public group, authorization is granted, even if no token or an invalid token were provided. (Then jump to 6.)
2. If no token or an invalid token (wrong signature or expired) are provided, authorization is rejected.
3. If audience is non-empty and does not intersect the audience claim of the provided token, authorization is rejected.
4. If scopes is non-empty and the scope claim of the provided token does not contain at least one permission group that covers
   the requested operation, authorization is rejected.
5. If the permissions claim of the provided token does not contain at least one permission, predefined permission group or custom
   permission group that covers the requested operation, authorization is rejected.
6. If policies is enabled and the PDP returns Deny, authorization is rejected.

Configuration

Name	Default	Description	Type	Since
enabled	true	Option to disable access control.	boolean	v3.3
publicScopes	[read]	Deprecated, see `groups'. List of permissions that every user possesses, if authenticated or not.	array	v3.3
groups	{public: [read]}	Definition of custom permission groups, the key is the group name, the value a list of permissions and/or predefined permission groups. The group public defines the list of permissions that every user possesses, if authenticated or not.	object	v3.5
scopes	[]	If non-empty, OAuth2 Scopes are added to the OpenAPI definition. Then only tokens that contain at least one scope that covers the requested operation are accepted. Scopes reuse permissions groups, values are the types of permission groups that should be used: BASE (e.g. read), PARENT (e.g. data), MAIN (e.g. data:read) and CUSTOM (everything defined in groups besides public).	array	v3.5
audience	[]	If non-empty, only tokens that contain at least one of the given values in the audience claim are accepted.	array	v3.5
policies	null	Optional additional authorization layer using a Policy Decision Point defined in the global configuration, see Policies.	object	v3.5

Policies

Name	Default	Description	Type	Since
enabled	false	Enable an additional authorization layer using a Policy Decision Point defined in the global configuration.	boolean	v3.5
attributes	{}	Add the given attributes to the request sent to the Policy Decision Point. Keys are attribute ids, values are single key objects using either constant for a fixed string , property for a property path or parameter for a query parameter. Attributes using property are only relevant for operations involving features. May be defined per collection.	object	v3.5
obligations	{}	Applies the given attributes of obligations returned by the Policy Decision Point. Keys are attribute ids, values are single key objects using parameter for a query parameter. Parameters defined in an obligation will overwrite parameters in the request with the exception if filter, which is merged using AND, May be defined per collection.	object	v3.5

Examples

See the API configuration of the API Vineyards in Rhineland-Palatinate, Germany.

Storage

API configurations reside under the relative path store/entities/services/{apiId}.yml in the data directory or in the Store (new) as entities with type services.