dd-eco-api

Specifications of the specialized version of the DD-API for ecology

View project on GitHub

Requirements and recommendations

Notes

must and required means that the implementation of this is mandatory. should means that the implementation of this is optional, but recommended.

Measurements

A minimal measurement should consist of at least the following properties:

  • measurementdate: (when was the measurement taken)
  • measurementlocation: (where was the measurement taken)
  • unit: the unit that the measured value was expressed in. Examples are: n (amount, counted), kg (mass), cm (length), abundance (items/m2)
  • quantity: the quantity that the measurement described. Examples are: height, length, concentration, acidity (pH), visibility
  • parameter: the parameter that was measured. Examples: chloride, phytoplankton, oxygen. An example where parameter is not required, is quantity visibility
  • measuredvalue: the measured value. This does not always need to be numeric. Example where non-numeric values are used are color, odor, visibility (good, poor)
  • compartment: the compartment in which the measurement took place, for instance surface water, air, shore

It is recommended that measurements have:

  • externalkey: specifies an immutable ‘id’ or the entity, something consumers can depend on. It is recommended to never use internal keys.
  • changedate: specified when the measurement was most recently changed (added, updated).

Units, quantities, parameters, measured values and compartments should be conform the AQUO standard where possible. Dates must be in ISO 8601 format.

Endpoints

  • An endpoint named /v<version>/endpoints is required, which lists the available endpoints known by the server.
  • An endpoint named /v<version>/measurements is required. This will return measurements (the goal of this API specification). There will be data directly referencing other endpoints: /measurements should provide all relevant data by itself.
  • All other endpoints are considered Discovery endpoints and optional, giving more specific information on entities used in the /measurements endpoint.

  • The following endpoints should be available:

    • /quantities
    • /parameters
    • /units

  • It is recommended to have the following endpoints:

    • /compartments
    • /measurementobjects (locations)
  • All endpoints (except /endpoints itself) should provide a sub-endpoint called [/filters](filtersendpoint.md). The purpose of [/filters](filtersendpoint.md) is to return a list of known fields that can be used for filtering, together with the comparers they support for the specific fields. This is essential for the consumer.
  • All non-error-responses (except for /filters sub-endpoints) must use the same structure: first a paging block, then the provider block and lastly the results block.
  • All endpoints (except /filters sub-endpoints) must implement the specified pagination algorithm.
  • All error responses must adhere to the error response specification.
  • The provider should provide their version of the DD-ECO-API specification as an OAS 3.x in JSON format.
  • The provider should provide an easy-to-reach (and find!) demo-environment of their implementation (either free or protected by an API key) and notify the DD-ECO-API maintainers of the URI of the implementation. This can also be used for compliancy tests or for testing what implications future features have.
  • The provider should implement content compression.
  • The provider should implement content security for non- or semi public data.
  • The provider should implement a method to retrieve what entities where removed since a specific date (/removed sub-endpoint).

Discovery

The provider should provide endpoints that specify what entities are known and provided by the service.

In addition, the provider can choose to add endpoints that provide data specific for their system. For example: the AquaDesk DD-ECO-API provider has endpoints for taxon literature, measurement packages, etc.

All endpoints provided by the provider, must be listed in the /endpoints endpoint.

GET and POST

Primarily, the DD-ECO-API only supports GET requests. However, in some circumstances the data that need to be passed to the DD-ECO-API is more than either the client can send or the provider can receive.

An example of this is a very detailed WKT or GeoJSON definition for an area. This can yield data in the megabyte ranges, well over the safe transmission limits (about 2K).

In these cases, where the provider can consider allowing the client to pass the filter through the body by using a POST.

The usage of a POST may seem contradicting, since a POST means that a resource needs to be created.

However, passing Filter Syntax can be considered creating a resource, namely a search context. POST does not define that a permanent resource needs to be created.