Binding: HTTPS

This specification defines a RESTful API over HTTPS for the Catalog Protocol.

• 1 Introduction

  • 1.1 Prerequisites

  • 1.2 Catalog Error

• 2 Path Bindings

  • 2.1 The catalog/request Endpoint (Provider-side)

  • 2.2 The catalog/datasets/:id Endpoint (Provider-side)

• 3 Technical Considerations

  • 3.1 Pagination

  • 3.2 Compression

• 4 The Well-Known Proof Metadata Endpoint

1 Introduction

1.1 Prerequisites

1. The <base> notation indicates the base URL for a Catalog Service endpoint. For example, if the base Catalog URL is api.example.com, the URL https://<base>/catalog/request will map to https//api.example.com/catalog/request.

2. All request and response messages must use the application/json media type.

1.2 Catalog Error

In the event of a request error, the Catalog Service must return an appropriate HTTP code and a Catalog Error in the response body.

2 Path Bindings

Endpoint	Method	Description
https://provider.com/catalog/request	POST	Section 2.1.1
https://provider.com/catalog/datasets/:id	GET	Section 2.2.1

2.1 The catalog/request Endpoint (Provider-side)

2.1.1 POST

Request

The Catalog Request Message corresponds to POST https://<base>/catalog/request:

POST https://provider.com/catalog/request

Authorization: ...

{
  "@context":  "https://w3id.org/dspace/2024/1/context.json",
  "@type": "dspace:CatalogRequestMessage",
  "dspace:filter": {}
}

• The Authorization header is optional if the Catalog Service does not require authorization. If present, the contents of the Authorization header are detailed in the Authorization section.

• 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 Catalog request. If a filter expression is not supported by an implementation, it must return a HTTP 400 (Bad Request) response.

Response

If the request is successful, the Catalog Service must return an HTTP 200 (OK) with a response body containing a Catalog (which is a profiled DCAT Catalog type described by the Catalog Protocol).

2.2 The catalog/datasets/:id Endpoint (Provider-side)

2.2.1 GET

Request

The Dataset Request Message corresponds to GET https://<base>/catalog/datasets/:id}:

GET https://provider.com/catalog/datasets/{id}

Authorization: ...

{
  "@context":  "https://w3id.org/dspace/2024/1/context.json",
  "@type": "dspace:DatasetRequestMessage",
  "dspace:dataset": "urn:uuid:3dd1add8-4d2d-569e-d634-8394a8836a88"
}

• The Authorization header is optional if the Catalog Service does not require authorization. If present, the contents of the Authorization header are detailed in the Authorization section.

Response

If the request is successful, the Catalog Service must return an HTTP 200 (OK) with a response body containing a Dataset (which is a DCAT Dataset type described by the Catalog Protocol).

3 Technical Considerations

3.1 Pagination

A Catalog Service may paginate the results of a Catalog Request Message. 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.

The following request sequence demonstrates pagination:

Link: <https://provider.com/catalog?continuationToken=f59892315ac44de8ab4bdc9014502d52>; rel="next"

{
  "@context":  "https://w3id.org/dspace/2024/1/context.json",
  "@type": "dcat:Catalog",
  ...
}

Second page response:

Link: <https://provider.com/catalog?continuationToken=a59779015bn44de8ab4bfc9014502d53>; rel="previous"
Link: <https://provider.com/catalog?continuationToken=f59892315ac44de8ab4bdc9014502d52>; rel="next"

{
   "@type": "dcat:Catalog",
   ...
}

Last page response:

Link: <https://provider.com/catalog?continuationToken=bn9556075bn44de8ab4bfc9014582t76>; rel="previous"

{
   "@type": "dcat:Catalog",
   ...
}

3.2 Compression

Catalog Services MAY compress responses to a Catalog Request by setting the Content-Encoding header to gzip as described in the HTTP 1.1 Specification.

4 The Well-Known Proof Metadata Endpoint

When an implementation supports protected Datasets, 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:

/.well-known/dspace-trust

The contents of the response is a JSON object defined by individual trust specifications and not defined here.

Note that if multiple Connectors 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.