OAI-PMH API (v3)

https://github.com/folio-org/mod-oai-pmh

Table of contents

OAI-PMH Business Logic API

The Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH) provides an application-independent interoperability framework based on metadata harvesting. This module supports the OAI-PMH as a means of exposing FOLIO metadata.

OAIPMH Repository

Service that processes OAI-PMH requests in RESTfull way

GET /oai/records

GET /oai/records
Query Parameters
  • verb: required (string)

    verb that specifies oai-pmh request type

  • identifier: (string)

    parameter that is used for GetRecord and ListMetadataFormats requests

  • resumptionToken: (string)

    flow control token returned by a ListIdentifiers request that issued an incomplete list

  • from: (string)

    UTC datetime value, which specifies a lower bound for datestamp-based selective harvesting

    Example:

    2018-10-15T15:16:17Z
  • until: (string)

    UTC datetime value, which specifies a upper bound for datestamp-based selective harvesting

    Example:

    2018-10-22T23:22:21Z
  • set: (string)

    setSpec value, which specifies set criteria for selective harvesting

  • metadataPrefix: required (string)

    metadata prefix of the format that should be included in the metadata part of the returned record

Response 200

Successful response. As well failure response can be responded with 200 status code in case the repository.errorsProcessing setting equals '200' and occurred error relates to OAIPMH level error.

Body

Media type: text/xml

Type: any

Example:

<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/
         http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
  <responseDate>2002-02-08T08:55:46Z</responseDate>
  <request verb="GetRecord" identifier="oai:arXiv.org:cs/0112017"
           metadataPrefix="oai_dc">http://arXiv.org/oai2</request>
  <GetRecord>
   <record>
    <header>
      <identifier>oai:arXiv.org:cs/0112017</identifier>
      <datestamp>2001-12-14</datestamp>
      <setSpec>cs</setSpec>
      <setSpec>math</setSpec>
    </header>
    <metadata>
      <oai_dc:dc
         xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/"
         xmlns:dc="http://purl.org/dc/elements/1.1/"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/
         http://www.openarchives.org/OAI/2.0/oai_dc.xsd">
        <dc:title>Using Structural Metadata to Localize Experience of
                  Digital Content</dc:title>
        <dc:creator>Dushay, Naomi</dc:creator>
        <dc:subject>Digital Libraries</dc:subject>
        <dc:description>With the increasing technical sophistication of
            both information consumers and providers, there is
            increasing demand for more meaningful experiences of digital
            information. We present a framework that separates digital
            object experience, or rendering, from digital object storage
            and manipulation, so the rendering can be tailored to
            particular communities of users.
        </dc:description>
        <dc:description>Comment: 23 pages including 2 appendices,
            8 figures</dc:description>
        <dc:date>2001-12-14</dc:date>
      </oai_dc:dc>
    </metadata>
  </record>
 </GetRecord>
</OAI-PMH>

Response 400

Bad request, some of parameters has invalid values or incompatible parameters were passed.

Body

Media type: text/xml

Type: any

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
    <responseDate>2020-05-14T07:49:29Z</responseDate>
    <request set="all" metadataPrefix="oai_dc">http://localhost:9701/oai/eyJzIjoiblo1NkYzTGVBYSIsInQiOiJkaWt1IiwidSI6ImRpa3VfYWRtaW4ifQ</request>
    <error code="badVerb">Bad verb. Verb 'WrongVerbName' is not implemented</error>
</OAI-PMH>

Response 404

When specific object ot group of objects weren't find by passed via parameters search criteria (from, until, identifier and etc.)

Body

Media type: text/xml

Type: any

Example:

<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/
         http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
  <responseDate>2001-06-01T19:20:30Z</responseDate>
  <request verb="ListSets">
           http://purl.org/alcme/etdcat/servlet/OAIHandler</request>
  <error code="noRecordsMatch"/>
</OAI-PMH>

Response 422

Specified metadataPrefix is not supported or exist.

Body

Media type: text/xml

Type: any

Example:

<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/
         http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
  <responseDate>2002-02-08T08:55:46Z</responseDate>
  <request verb="GetRecord" identifier="oai:arXiv.org:quant-ph/9901001"
           metadataPrefix="oai_marc">http://arXiv.org/oai1</request>
  <error code="noMetadataFormats"/>
</OAI-PMH>

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

Response 503

OAI-PMH service is disabled

Body

Media type: text/xml

Type: any

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
    <responseDate>2020-05-14T07:49:29Z</responseDate>
    <request set="all" metadataPrefix="oai_dc">http://localhost:9701/oai/eyJzIjoiblo1NkYzTGVBYSIsInQiOiJkaWt1IiwidSI6ImRpa3VfYWRtaW4ifQ</request>
    <error code="serviceUnavailable">OAI-PMH service is disabled</error>
</OAI-PMH>