Permalink
Switch branches/tags
Nothing to show
Find file Copy path
168 lines (156 sloc) 5.89 KB
#%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"