lagvaelgeren

Datakatalog service

The datakatalog service is a REST API service containing a catalog of Dataset metadata including technical details about Dataset sources, for example WMS services, so that they can be consumed in a mapping solution.

image

To fully understand the endpoints and schemas that the REST API is exposing we recommend to study the data model that is the API is based on. The data model is documented here.

Data source protocols WMS, WMTS and WFS are industry standards that most mapping software can consume and open specifications extensively documented at OGC.

Getting Started

The Datakatalog service REST API is formally described and documented here.

Examples

A basic example request is a HTTP GET request against URL https://datakatalog.miljoeportal.dk/api/datasets which will give you all Datasets with all attributes but without any related information.

To get related information without additional requests the include parameter (part of JSON-API) can be used. For example, https://datakatalog.miljoeportal.dk/api/datasets?include=wmsSource will provide the same Datasets as the previous example but including the related WmsSource that describes a WMS service which can the be used by the consumer to request actual data as map images.

JSON-API

As detailed in the API documentation, the REST API adheres to the JSON-API standard. This allows the payload, in JSON, to be parsed by existing client implementations and offers standardised means to fetch hierarchical structures and filtering included or out of band. However, note that JSON-API is made to be conformant to general REST API principles so it’s relatively straight forward to consume and parse without any external dependencies. We recommend to use or be inspired by existing implementations.

If you are familiar with GraphQL you might note that there are some similarities in the scope and goals of these specifications. The largest difference between these two specifications is that JSON-API is more RESTful and HTTP native than GraphQL. One detail that have shown to cause confusion and/or concern is that JSON-API does not inline related data in a nested structure, instead it is flattened out structurally by id linkage in the payload. For more information consult this section of the JSON-API specification and for more background over this design choice you can find a comprehensive discussion here.

Custom query parameters

In addition to standard JSON-API query string parameters the API has some additional parameters for all resources for localization and usage tracking support.

Localization

The content of the datakatalog service is by default in Danish but English can optionally be requested. Note that Danish text will still be returned if translation is missing.

Usage tracking

To better understand and support the usage of the datakatalog service a set of optional anonymised usage tracking information can be supplied by the caller. We recommend to use them in general as it will be helpful to support the use of the service better, also in case of any technical issues.