/api/v1/oai

OAI-PMH endpoint. Implements the Open Archives Initiative Protocol for Metadata Harvesting (version 2.0) so external harvesters can pull metadata from fylr. The protocol uses a single URL with a verb query parameter and returns XML.

Must be enabled in the base config (fylr.oai_pmh.enabled = true), otherwise every request returns HTTP 400 with code: OAIpmhNotEnabled. Protocol-level errors are returned inside the XML response body as an <error code="…"> element AND carry the matching HTTP status: badArgument / badVerb / cannotDisseminateFormat / badResumptionToken → 400, idDoesNotExist → 404, internal failures → 500. Only a successful harvest is 200 OK.

The endpoint requires no rights and accepts anonymous requests: when no user can be derived from the session, the built-in system:oai_pmh user is used. There is no read-only-mode guard. A ListRecords or GetRecord harvest logs an OBJECT_DOWNLOAD event per record (written in a background transaction), but the request itself runs in a read transaction — nothing else is persisted.

GET /oai — OAI-PMH protocol entry point.

OAI-PMH protocol entry point.

get

The behaviour depends on the verb query parameter. See the OAI-PMH specification for the full request/response shape.

Authorizations

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Query parameters

verbstring · enumRequired

OAI-PMH verb.

Possible values:

identifierstringOptional

OAI-PMH record identifier, e.g. oai:<namespace_identifier>:<uuid>. The prefix is oai: plus the configured fylr.oai_pmh.namespace_identifier (just oai: when unset). Required for GetRecord; ignored by the other verbs.

metadataPrefixstringOptional

Metadata format prefix. Required by fylr for GetRecord and ListRecords; per the OAI-PMH spec it is also expected for ListIdentifiers, though fylr does not currently reject a ListIdentifiers request that omits it. Built-in values: oai_dc and easydb. Each XSLT sheet enabled for OAI-PMH in the base config adds a xslt-<name> prefix. Call verb=ListMetadataFormats to enumerate the prefixes available on a given instance. An unknown prefix yields <error code="cannotDisseminateFormat"> (HTTP 400).

setstringOptional

Set spec (optional for ListIdentifiers, ListRecords).

fromstring · date-timeOptional

UTC datestamp lower bound (UTC date or full datetime accepted, per the OAI-PMH spec).

untilstring · date-timeOptional

UTC datestamp upper bound.

resumptionTokenstringOptional

Resumption token issued by a previous ListIdentifiers, ListRecords or ListSets response. Must not be combined with from, until, limit, set or metadataPrefix, and must match the verb of the request that issued it; an expired token yields <error code="badArgument">.

limitintegerOptional

fylr extension (not part of OAI-PMH). Maximum records per page for ListRecords / ListIdentifiers. Defaults to the base config fylr.oai_pmh.records_limit (else 100); values are clamped to a maximum of 10000. Must not be combined with resumptionToken.

offsetintegerOptional

fylr extension (not part of OAI-PMH). Starting offset into the result list. Normally supplied via resumptionToken instead.

Default: 0

event.infostringOptional

fylr extension (not part of OAI-PMH). JSON object string attached to the OBJECT_DOWNLOAD event logged for each record harvested by a ListRecords or GetRecord request (e.g. {"custom_info":"..."}).

Responses

200

Successful OAI-PMH response document. Protocol-level errors are encoded inside the XML body as <error code="…"> and also set the matching HTTP status (400 / 404 / 500), so this 200 applies to successful harvests only.

text/xml

stringOptional

An OAI-PMH XML response.

400

Either OAI-PMH is disabled in the base config (fylr.oai_pmh.enabled = false) — a JSON error envelope with code: OAIpmhNotEnabled — or a protocol-level request error (badArgument, badVerb, cannotDisseminateFormat, badResumptionToken) returned as an OAI-PMH XML document with an <error code="…"> element.

404

Protocol-level error idDoesNotExist (the GetRecord identifier matched no readable object) returned as an OAI-PMH XML document with an <error code="idDoesNotExist"> element.

text/xml

500

Internal failure while building the response, returned as an OAI-PMH XML document with <error code="internalServerError">.

text/xml

text

HEAD /oai — HEAD on the OAI-PMH endpoint.

HEAD on the OAI-PMH endpoint.

head

Runs the same logic as GET /oai (same handler) but the harvester receives only the response headers and HTTP status — no body. A malformed request still yields the matching status, e.g. an unknown verb returns 400.

Authorizations

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Query parameters

verbstringRequired

Responses

200

OAI-PMH service is available and the request succeeded; no body is returned.

No content

400

OAI-PMH is disabled, or the request is malformed (e.g. an unknown verb); no body is returned.

404

Protocol-level not-found error (idDoesNotExist); no body is returned.

500

Internal failure while building the response; no body is returned.

No content