Binding: HTTPS
Last updated
Dataspace Protocol
Last updated
This specification defines a RESTful API over HTTPS for the Catalog Protocol.
The <base> notation indicates the base URL for a endpoint. For example, if the base URL is api.example.com, the URL https://<base>/catalog/request will map to https//api.example.com/catalog/request.
All request and response messages must use the application/json media type.
catalog/request Endpoint (Provider-side)Request
Response
catalog/datasets/:id Endpoint (Provider-side)Request
Response
The following request sequence demonstrates pagination:
Second page response:
Last page response:
The contents of the response is a JSON object defined by individual trust specifications and not defined here.
In the event of a request error, the must return an appropriate HTTP code and a in the response body.
The corresponds to POST https://<base>/catalog/request:
The Authorization header is optional if the does not require authorization. If present, the contents of the Authorization header are detailed in the .
The filter property is optional. If present, the filter property can contain an implementation-specific filter expression or query to be executed as part of the request. If a filter expression is not supported by an implementation, it must return a HTTP 400 (Bad Request) response.
If the request is successful, the must return an HTTP 200 (OK) with a response body containing a (which is a profiled DCAT Catalog type described by the Catalog Protocol).
The corresponds to GET https://<base>/catalog/datasets/:id}:
The Authorization header is optional if the does not require authorization. If present, the contents of the Authorization header are detailed in the .
If the request is successful, the must return an HTTP 200 (OK) with a response body containing a (which is a DCAT Dataset type described by the Catalog Protocol).
A may paginate the results of a . Pagination data must be specified using Web Linking and the HTTP Link header. The Link header will contain URLs for navigating to previous and subsequent results. Only the next and previous link relation types must be supported. Note that the content and structure of the link query parameters is not defined by the current specification.
MAY compress responses to a by setting the Content-Encoding header to gzip as described in the HTTP 1.1 Specification.
When an implementation supports protected , it may offer a proof metadata endpoint clients can use to determine proof requirements. If the implementation offers a proof data endpoint, it must use the dspace-trust Well-Known Uniform Resource Identifier at the top of the path hierarchy:
Note that if multiple are hosted under the same base URL, an arbitrary path segment appended to the base well-known URL can be used, for example, https://example.com/.well-known/dspace-trust/connector1. In this case, the document retrievable at the dspace-trust path segment must contain all the child paths.