/
Generic API requirements

Generic API requirements

Deze pagina’s zijn in het engels ten behoeve van mogelijk internationale ontwikkelaars

This page defines a number of requirements that all trust framework APIs must conform to.

DSGO.Basis: Parties MUST validate that all received API calls conform to the DSGO trust framework

DSGO.Basis: Parties MUST validate that all responses to API calls conform to the DSGO trust framework

Endpoint urls

All URLs of API endpoints within the trust framework should follow the following common structure.

DSGO.Basis: Parties MUST define the default base URL of API endpoints following the <domain-name>/<path>/resources format, where <domain-name> is server specific and <path> is an optional URL path

DSGO.Basis: Parties MUST define the default base URL of API endpoints without a trailing slash

Body content

To ensure that API performance requirements can be met, the amount of data in an API call should be limited. Depending on the service, only a reasonable amount of data should be included in API calls. If the party sending the API request requires additional or specific data, this can be requested using optional URL query parameters.

DSGO.Basis: Parties SHOULD limit API calls to include only a reasonably sized amount of data

DSGO.Basis: Parties MUST NOT include HTTP bodies in GET or DELETE requests

Query parameters

URL query parameters may be used to modify API queries. A query option is a set of query string parameters applied to a resource that can help control the amount of data being returned for the resource in the URL. A query option requests that a service perform a set of transformations on its data before returning the results. These transformations include functions such as filtering, sorting, searching etc. Depending on the specific resource, the use of URL parameters may be relevant. The trust framework follows the OData 4.01 query options in the use of URL parameters.

DSGO.Basis: Parties MAY include query options for functionalities such as filter, sort, and page in their API endpoint as defined in OData 4.01

DSGO.Basis: Parties MUST reject any requests that contain unsupported url parameters with a 501 Not Implemented as defined in OData 4.01

Caching

Often, data is temporarily stored in a place different from the source storage location of the data to allow faster access to the data. This is called caching and is a way to improve efficiency.

Source: iSHARE (v2.0) - Caching

Caching is a way to boost performance efficiency. Often data is temporarily stored on a different medium, to enable faster access to the data.For every API exposed under iSHARE caching MUST be made explicit to the API consumer.

If a response is not cacheable it MUST contain the following headers:

Cache-Control: no-store

Pragma: no-cache

If a response is cacheable it MUST contain the following headers:

Cache-Control: max-age=31536000
Note: max-age MAY vary

The trust framework follows the iSHARE (v2.0) and the Centre of Excellence for Data Sharing and Cloud (CoE-DSC) Use Case Implementation Guide in regard to caching.

DSGO.Basis: Parties MUST make caching explicit to API users

DSGO.Basis: Parties MUST include the following headers in the API response when it is not cacheable:
cache-control: no-store
pragma: no-cache

DSGO.Basis: Parties MUST include the following headers in the API response when it is cacheable:
cache-control: max-age=31536000
Note: max-age MAY vary