Routes

These are the read routes of the RO-Crate API specification, version 0.4.0, whose OpenAPI reference is the contract clients code against. arocapi is a read-only catalogue: it reports deposit: { supported: false } from /capabilities and doesn’t provide the specification’s optional deposit, RO-Crate or entity-delete routes.

Deposits are coming

Support for the deposit routes is coming soon. Until then, you fill the database and search index yourself; see Your first API.

Paths are relative to the prefix arocapi is registered with. Entity and file ids are URLs, encoded as one path segment, e.g. /entity/http%3A%2F%2Fexample.com%2Fentity%2F1.

Method	Path	Returns	Guarded by
GET	/capabilities	API version and search capabilities	nothing
GET	/entities	A page of entity Records	visibility
GET	/entity/:id	One entity Record	visibility
GET, HEAD	/entity/:id/metadata	The entity’s RO-Crate metadata	visibility, Metadata access
GET	/files	A page of file Records	visibility
GET, HEAD	/file/:id	The file’s Content	visibility, Content access
POST	/search	A page of matching entity Records and facets	visibility

Refusals and validation errors are listed under Error responses. The outcome of each route for Hidden, Accessible and Denied entities is under Route by route. Entities & hierarchy explains memberOf, and the request lifecycle the order in which each route runs your code.

GET /capabilities

Declares the RO-Crate API version and, as search, the search backend’s capabilities: the filters, facets and sorts clients may use, the search types and whether geo is supported. The same for every request.

{
  "apiVersion": "0.5.0",
  "deposit": { "supported": false },
  "tombstonePolicy": "404",
  "extensions": {},
  "search": {
    "filters": { "inLanguage": { "type": "string", "label": "Language" } },
    "facets": { "inLanguage": { "label": "Language" } },
    "sorts": { "name": { "label": "Name" } },
    "searchTypes": { "basic": {} },
    "geo": { "supported": false }
  }
}

GET /entities

Query	Type	Default	Purpose
memberOf	URL	none	Only direct members of this entity.
entityType	URL, repeatable	none	Only these entity types.
limit	integer, 1 to 1000	100	Page size.
offset	integer, 0 or more	0	Entities to skip.
sort	id, name, createdAt, updatedAt	id	Sort field.
order	asc, desc	asc	Sort direction.

Response: { total, entities }. total counts Visible entities matching the query, and each entity has been through the entity transformers.

Repeat entityType for several types: ?entityType=A&entityType=B. Commas aren’t separators, so ?entityType=A,B is the single type A,B. Blank values are ignored.

GET /entity/:id

Response: the entity after the entity transformers, with its access. Access isn’t checked here: a Visible entity’s Record is always returned.

GET /entity/:id/metadata

Response: the RO-Crate metadata from the storage backend’s metadata half, as application/ld+json, or a 302 for a redirect delivery. HEAD answers with the headers GET would send, and a 302 for a redirect. No query parameters.

GET /files

Query	Type	Default	Purpose
memberOf	URL	none	Only files whose entity is a member of this.
limit	integer, 1 to 1000	100	Page size.
offset	integer, 0 or more	0	Files to skip.
sort	id, filename, createdAt, updatedAt	id	Sort field.
order	asc, desc	asc	Sort direction.

Response: { total, files }, each file after the file transformers. A file is Visible when its file entity is.

GET /file/:id

Response: the Content from the storage backend’s content half, or a 302 for a redirect delivery. HEAD answers with the headers GET would send, and a 302 for a redirect. Both take disposition, filename and noRedirect; see query parameters.

POST /search

JSON body:

Field	Type	Default	Purpose
query	string, required	none	Search text. Empty matches every visible entity.
searchType	a search type in /capabilities	basic	basic is free text the backend interprets its own way.
filters	Record<string, string[] | { gte?, lte? } | { gte?, lte? }[]>	none	Per declared filter, exact values or, for date and number filters, inclusive ranges: any value or range within a field, every field. See Dates.
boundingBox	{ topRight: { lat, lng }, bottomLeft: { lat, lng } }	none	Only entities inside, when geo is supported.
geohashPrecision	integer, 1 to 12	none	Return a geohash grid over the box; needs boundingBox.
limit	integer, 1 to 1000	100	Page size.
offset	integer, 0 or more	0	Hits to skip.
sort	a sort in /capabilities, or relevance	relevance	Sort field. relevance is best match first.
order	asc, desc	asc	Sort direction.

An undeclared filter key, sort or search type, a bad range, a range on a string or boolean filter, and boundingBox or geohashPrecision when geo isn’t supported are a 400 VALIDATION_ERROR. A query the backend can’t run is a 422.

Response:

Field	Type	Purpose
total	number	Matching Visible entities, exact.
searchTime	number	Time spent in the search backend, in milliseconds.
entities	array	Entities in hit order after the entity transformers, each with the backend’s searchExtra (such as score) if it gives one.
facets	Record<string, { name, count }[]>	One list per declared facet, ordered by count, then name; empty when nothing matches.
geohashGrid	Record<string, number>	Counts per geohash, when the backend gives them.