RO-Crate API
Introduction
This API offers a standardised approach to interacting with RO-Crate metadata in repositories that host diverse media archives, such as PARADISEC. Building on the RO-Crate specification, the endpoints here facilitate the creation, retrieval, and management of digital collections, ensuring metadata is compliant and discoverable.
RO-Crate (Research Object Crate) is a lightweight approach to packaging research data with machine-readable metadata. By using this API, developers and archives can programmatically interface with RO-Crate-compliant collections, enabling consistent handling of metadata and files.
This documentation covers what a valid implementation of this API should look like.
Authentication
It is expected that most archives will allow public access but there will typically be entities which are private or require authorization.
When authentication is required, an API implementation MUST implement OAuth2 and it is recommended that OpenID is also added for simpler configuration and discoverability.
Write operations — the deposit and RO-Crate endpoints — require the coarse OAuth2 write scope. Finer-grained authorisation policy (who may deposit what) is implementation-defined.
Rate Limiting
API implementations MAY implement rate limiting to ensure fair usage and system stability. When rate limiting is active, responses will include rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) and will return a 429 status code when limits are exceeded.
Extensions
The core specification can be extended through a curated registry of extensions defined in this document. Every extension has a stable identifier, a schema, and semantics. Implementations choose which extensions to implement and declare them through the GET /capabilities endpoint. Extension properties appear in core schemas as optional fields tagged with an x-extension annotation. See the Extensions guide for the full extension model.
Deposits and RO-Crates
Deposit is part of the core specification but is optional to provide: a read-only catalog remains conformant without it. All writes flow through deposit sessions against RO-Crates — a metadata document plus all the files it references, deposited and stored as a unit. The implementation materialises catalog entities from RO-Crates by its own rules; entities are read-only projections and have no write endpoints of their own.
Every implementation declares where it stands: the deposit block in GET /capabilities is always present, and its required supported flag states plainly whether the deposit surface is available.
Authentication
- API Key: ApiKey
- OpenID Connect: OpenID
- OAuth 2.0: OAuth2
API key for authentication. Provides a simpler alternative to OAuth2 for server-to-server integrations.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-API-Key |
It is recommended that API implementations implement OpenID to make discovery and implementation easier.
Security Scheme Type: | openIdConnect |
|---|---|
OpenID Connect URL: | /.well-known/openid-configuration |
API implementations that contain data which needs to be protected MUST implement authorisation using OAuth 2
Security Scheme Type: | oauth2 |
|---|---|
OAuth Flow (authorizationCode): | Token URL: /oauth/token Authorization URL: /oauth/authorize Scopes:
|
Contact Issues:
License MIT