oai-pmh.raml

#%RAML 1.0
title: OAI-PMH API
baseUri: https://github.com/folio-org/mod-oai-pmh
version: v1
protocols: [ HTTP, HTTPS ]

documentation:
  - title: OAI-PMH Business Logic API
    content: |
      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.

# xsd schemas are not properly handled by RAML at the moment
# see https://issues.folio.org/browse/RMB-270 for more details
#types:
#  oai-pmh:
#    type: !include schemas/OAI-PMH.xsd#OAI-PMH
#    description: OAI-PMH root element

traits:
  partionable: !include traits/partitionable.raml
  selective: !include traits/selective.raml
  metadataPrefix: !include traits/metadataPrefix.raml

resourceTypes:
  list: !include rtypes/list.raml

/oai:
  displayName: OAIPMH Repository
  description: Service that processes OAI-PMH requests in RESTfull way
  /records:
    displayName: Records
    description: The endpoint for "ListRecords" OAI-PMH verb which is used to harvest records from a repository.
    type:
      list:
        exampleCollection: !include examples/records.sample
    get:
      is: [ partionable, selective, metadataPrefix ]
      responses:
        404:
          description: "Item with a given ID and selective harvesting params (if any) not found"
          body:
            application/xml:
              #schema: oai-pmh
              example:
                strict: false
                value: !include examples/no_records_error.sample

    /{id}:
      displayName: Record
      description: The endpoint for "GetRecord" OAI-PMH verb which is used to retrieve an individual metadata record from a repository.
      uriParameters:
        id:
          description: The unique identifier of the item in the repository
          type: string
      get:
        description: Retrieve record with given Id
        is: [ metadataPrefix ]
        responses:
          200:
            description: "Returns item with a given ID"
            body:
              application/xml:
                #schema: oai-pmh
                example:
                  strict: false
                  value: !include examples/record.sample
          400:
            description: "Bad request, e.g. malformed query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response."
            body:
              application/xml:
                #schema: oai-pmh
                example:
                  strict: false
                  value: !include examples/metadata_prefix_error.sample
          404:
            description: "Item with a given ID and selective harvesting params (if any) not found"
            body:
              application/xml:
                #schema: oai-pmh
                example:
                  strict: false
                  value: !include examples/no_record_error.sample
          500:
            description: "Internal server error, e.g. due to misconfiguration"
            body:
              text/plain:
                example: "Internal server error, contact administrator"

  /identifiers:
    displayName: Identifiers
    description: The endpoint for "ListIdentifiers" OAI-PMH verb which is an abbreviated form of "ListRecords", retrieving only headers rather than records from a repository.
    type:
      list:
        exampleCollection: !include examples/identifiers.sample
    get:
      is: [ partionable, selective, metadataPrefix ]
      responses:
        404:
          description: "Item with a given ID and selective harvesting params (if any) not found"
          body:
            application/xml:
              #schema: oai-pmh
              example:
                strict: false
                value: !include examples/no_records_error.sample


  /metadata_formats:
    displayName: MetadataFormats
    description: The endpoint for "ListMetadataFormats" OAI-PMH verb which is used to retrieve the metadata formats available from a repository.
    type:
      list:
        exampleCollection: !include examples/metadata_formats.sample
    get:
      queryParameters:
        identifier:
          description: 'unique identifier of the item in the repository from which the record must be disseminated'
          type: string
          required: false
      responses:
        404:
          description: "Item with a given ID and selective harvesting params (if any) not found"
          body:
            application/xml:
              #schema: oai-pmh
              example:
                strict: false
                value: !include examples/no_record_error.sample
        422:
          description: "The request was well-formed, but contains semantic errors"
          body:
            application/xml:
              #schema: oai-pmh
              example:
                strict: false
                value: !include examples/no_metadata_format_error.sample

  /sets:
    displayName: Sets
    description: The endpoint for "ListSets" OAI-PMH verb which is used to retrieve the set structure of a repository.
    type:
      list:
        exampleCollection: !include examples/sets.sample
    get:
      is: [ partionable ]

  /repository_info:
    displayName: RepositoryInfo
    description: The endpoint for "Identify" OAI-PMH verb which is used to retrieve information about a repository.
    get:
      description: Returns information about a repository
      responses:
        200:
          description: "Returns repository info"
          body:
            application/xml:
              #schema: oai-pmh
              example:
                strict: false
                value: !include examples/repository_info.sample
        500:
          description: "Internal server error, e.g. due to misconfiguration"
          body:
            text/plain:
              example: "Internal server error, contact administrator"