oai-pmh.raml

#%RAML 1.0
title: OAI-PMH API
baseUri: https://github.com/folio-org/mod-oai-pmh
version: v3
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

types:
  errors: !include raml-util/schemas/errors.schema

traits:
  partionable: !include traits/partitionable.raml
  selective: !include traits/selective.raml
  metadataPrefix: !include traits/metadataPrefix.raml
  validate: !include raml-util/traits/validation.raml

resourceTypes:
  list: !include rtypes/list.raml

/oai:
  displayName: OAIPMH Repository
  description: Service that processes OAI-PMH requests in RESTfull way
  /records:
    displayName: Verb
    description: The endpoint is the first entry point which is used for request validation and redirection to a prticular verb endpoint for further request processing.
    get:
      queryParameters:
        verb:
          description: 'verb that specifies oai-pmh request type'
          type: string
          required: true
        identifier:
          description: 'parameter that is used for GetRecord and ListMetadataFormats requests'
          type: string
          required: false
      is: [ partionable, selective, metadataPrefix ]
      responses:
        200:
          description: "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:
            text/xml:
              #schema: oai-pmh
              example:
                strict: false
                value: !include examples/record.sample
        400:
          description: "Bad request, some of parameters has invalid values or incompatible parameters were passed."
          body:
            text/xml:
              #schema: oai-pmh
              example:
                strict: false
                value: !include examples/bad_verb_error.sample
        404:
          description: "When specific object ot group of objects weren't find by passed via parameters search criteria (from, until, identifier and etc.)"
          body:
            text/xml:
              #schema: oai-pmh
              example:
                strict: false
                value: !include examples/no_records_error.sample
        422:
          description: "Specified metadataPrefix is not supported or exist."
          body:
            text/xml:
              #schema: oai-pmh
              example:
                strict: false
                value: !include examples/no_metadata_format_error.sample
        500:
          description: "Internal server error, e.g. due to misconfiguration"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
        503:
          description: "OAI-PMH service is disabled"
          body:
            text/xml:
              #schema: oai-pmh
              example:
                strict: false
                value: !include examples/service_unavailable.sample