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 must follow the following common structure.

DSGO.Basis: Parties MUST define the default base URL of the token endpoint following the <domain-name>/connect/token format, where <domain-name> is server specific.

DSGO.Basis: Parties MUST define the default base URL of all other endpoints following the <domain-name>/<path>/resources format, where <domain-name> is server specific. <path> is an optional URL path, which must be identical for all endpoints other than /token.

DSGO.Basis: Parties providing a SPARQL endpoint MUST offer a <domain-name>/<path>/<sparql> endpoint, where <sparql> is free to define by the data service provider (e.g. (GET) /sparql or (POST) /statements).

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

Pagination

within DSGO, the following endpoints for data service providers contain standardised pagination:

/GET dataServices (for data service providers)

Additionally, the following endpoints for the Central Participant Registry also contain standardised pagination:

Pagination request attributes

The following URL query parameters can be provided:

Query parameters		Type	Description

Query parameters		Type	Description
`page`	Optional	integer	Requests to return a specific page
`size`	Optional	integer	Sets the page size (number of items per page).

Pagination response attributes

The response is an object (for example for example a dataServicesInfo object or partiesInfo object) containing the pagination attributes as follows:

attributes		Type	Description

attributes		Type	Description
`count`	Required	integer	number of returned objects in current page
`totalCount`	Required	integer	Total number of objects available
`currentPage`	Required	integer	Number of the returned page
`pageSize`	Required	integer	Number of items per page
`totalPages`	Required	integer	Total number of pages available
`next`	Required	string	String representing the next request
`previous`	Required	string	String representing the previous request

DSGO.Basis: Parties MUST include pagination in the /dataServices endpoint, according to DSGO pagination rules

DSGO.Basis: Parties MAY include pagination in their data service endpoints, which SHOULD follow DSGO pagination rules

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

Generic API requirements