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.
Parties MUST validate that all received API calls conform to the DSGO trust framework
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.
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
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, only limited data should be returned in an API call. Therefore, the size of data sent via APIs is limited. If the party sending the API request requires additional or specific data, this can be requested using optional URL query parameters.
Parties SHOULD limit API responses to include only a reasonably sized amount of data
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.
Parties MAY include query options for functionalities such as filter, sort, and page in their API endpoint as defined in OData 4.01
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.
Parties MUST make caching explicit to API users
Parties MUST include the following headers in the API response when it is not cacheable:cache-control: no-storepragma: no-cache
Parties MUST include the following headers in the API response when it is cacheable:cache-control: max-age=31536000
Note: max-age MAY vary