Skip to content

catalog.binding.https.md

Latest commit

 

History

History
134 lines (93 loc) · 4.65 KB

catalog.binding.https.md

File metadata and controls

134 lines (93 loc) · 4.65 KB

Catalog HTTPS Binding {#catalog-http}

Introduction

This binding defines a RESTful Application Programming Interface (API) over HTTPS for the [=Catalog Protocol=].

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.

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.

Path Bindings

Endpoint Method Description
https://provider.com/catalog/request POST [[[#catalog-request-post]]]
https://provider.com/catalog/datasets/:id GET [[[#catalog-datasets-get]]]

Catalog Request Endpoint {#catalog-request-post}

Request

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

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

  • 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 MAY 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.

Dataset Request Endpoint {#catalog-datasets-get}

Request

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

GET https://provider.com/catalog/datasets/{id}
Authorization: ...
  • 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]]].

Response

If the request is successful, the [=Catalog Service=] MUST return an HTTP 200 (OK) with a response body containing a Dataset.

Technical Considerations

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/2025/1/context.jsonld",
  "@type": "Catalog",
  ...
}

Second page response:

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

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

Last page response:

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

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

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.