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 | 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
defaultsdirectory. - API level configuration.
- Collection level configuration.
- Optional deployment overrides in the
overridesdirectory.
Metadata
General metadata for the API (version, contact details, license information). Supported keys with affected resources:
version: API Definition,contactName: API Definition, HTML Landing PagecontactUrl: API Definition, HTML Landing PagecontactEmail: API Definition, HTML Landing PagecontactPhone: HTML Landing Page,licenseName: API Definition, HTML Landing Page, Feature Collections, Feature CollectionlicenseUrl: API Definition, HTML Landing Page, Feature Collections, Feature Collectionkeywords: HTML meta tages and schema:Dataset in HTML Landing Pageattribution: Landing Page, mapscreatorName: schema:Dataset in HTMLcreatorUrl: schema:Dataset in HTMLcreatorLogoUrl: schema:Dataset in HTMLpublisherName: schema:Dataset in HTMLpublisherUrl: schema:Dataset in HTMLpublisherLogoUrl: 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. | object | v3.1 |
expires | null | For the resources in the building block, the Expires header is set to the configured value. | object | 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).
The control mechanism is based on scopes, currently only two exist:
write: every operation with HTTP methodPOST,PUT,PATCHorDELETEread: any other operation
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.
| Name | Default | Description | Type | Since |
|---|---|---|---|---|
enabled | true | Option to disable access control. | boolean | v3.3 |
publicScopes | [read] | List of permissions that every user possesses, if authenticated or not. | array | v3.3 |
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.