University of Bristol Research Portal OAI-PMH

# authorship: derived by API Evangelist from live, unauthenticated probes of the endpoint
# on 2026-08-30. The University of Bristol publishes no such document; this is OURS, not theirs.
# x-method: derived
# x-source-url: https://research-information.bris.ac.uk/ws/oai
openapi: 3.1.0
info:
  title: University of Bristol Research Portal OAI-PMH
  summary: Institution-operated OAI-PMH 2.0 metadata harvesting interface for the University of Bristol Research Portal.
  description: |-
    Keyless, public OAI-PMH 2.0 harvesting interface operated by the University of Bristol at
    `research-information.bris.ac.uk`, on the university's own registrable domain (`bris.ac.uk`).

    OPERATOR: The research-information system behind this portal is Elsevier Pure. THIS interface
    is the OpenArchives OAI-PMH 2.0 protocol served from the institution's own host under the
    institution's own identifier namespace (`oai:research-information.bris.ac.uk:...`), which is
    the operator distinction this description turns on. Elsevier's own product API is a DIFFERENT
    surface at `/ws/api` — `info.title: "Pure API"`, `info.contact.email: pure-support@elsevier.com`,
    `servers: [{url: /ws/api}]`, 826 paths, api-key gated (verified 2026-08-30 by fetching
    https://research-information.bris.ac.uk/ws/api/openapi.json, 200, 1,740,065 bytes). That is the
    VENDOR's contract, is recorded in apis.yml as a tenant relationship, and is deliberately NOT
    described here.

    PROVENANCE: The University of Bristol publishes no OpenAPI description of this endpoint. This
    document was DERIVED from live, unauthenticated probes on 2026-08-30 — every operation,
    parameter, metadata prefix, set and error code below was observed in an actual response.
    Nothing is inferred from documentation or from another institution's deployment.

    OBSERVED AT PROBE TIME (2026-08-30):
      * 7 metadata formats: `mods` (MODS 3.8), `qdc`, `oai_dc`, `oai_cerif_openaire`
        (OpenAIRE CERIF profile 1.2), `xmetadiss`, `nl_didl`, `uketd_dc` (EThOS/UKETD).
      * 3,878 sets, including the seven OpenAIRE CRIS sets
        (`openaire_cris_publications`, `_patents`, `_persons`, `_orgunits`, `_events`,
        `_equipments`, `_products`), the Pure sets `persons:all`, `publications:all`,
        `publications:withFiles`, and per-year variants.
      * `completeListSize` of 590,974 for `ListIdentifiers`/`ListRecords` with `oai_dc`;
        page size 100 with a `resumptionToken`.
      * `completeListSize` of 9,750 for `openaire_cris_persons` under `oai_cerif_openaire`.
      * Every response advertises the OpenAIRE CERIF 1.2 profile in `xsi:schemaLocation`.

    TWO DEFECTS OBSERVED AND REPORTED AS OBSERVED, not smoothed over:
      1. `?verb=Identify` returns **HTTP 500** with a `text/html` Pure error page instead of an
         OAI-PMH `Identify` response. The mandatory OAI-PMH 2.0 self-description verb is therefore
         unavailable, which means `repositoryName`, `adminEmail`, `earliestDatestamp`,
         `deletedRecord` policy and `granularity` cannot be read from the repository itself.
      2. `?verb=ListRecords&metadataPrefix=oai_cerif_openaire&set=openaire_cris_persons` returns a
         `200` with an EMPTY `<ListRecords>` carrying only a `resumptionToken`
         (`completeListSize="9750"`) — a first page with zero records.

    OAI-PMH returns HTTP 200 for protocol-level errors and signals the condition in an
    `<error code="...">` element. Four error codes were provoked and observed; see errors/.
  version: '2.0'
  contact:
    name: University of Bristol Research Information Support
    url: https://research-information.bris.ac.uk/
  license:
    name: OpenArchives Initiative Protocol for Metadata Harvesting 2.0
    url: https://www.openarchives.org/OAI/openarchivesprotocol.html
  x-provenance:
    generated: '2026-08-30'
    method: derived
    source: live unauthenticated probes of https://research-information.bris.ac.uk/ws/oai
  x-operator: institution
servers:
  - url: https://research-information.bris.ac.uk/ws/oai
    description: University of Bristol Research Portal OAI-PMH 2.0 base URL (keyless)
tags:
  - name: OAI-PMH
    description: OpenArchives Initiative Protocol for Metadata Harvesting 2.0 verbs.
paths:
  /:
    get:
      tags: [OAI-PMH]
      summary: OAI-PMH 2.0 request
      operationId: oaiPmhRequest
      description: |-
        Single OAI-PMH 2.0 endpoint. The `verb` query parameter selects the operation. All six
        verbs execute anonymously; no API key, token or affiliation is required.

        `Identify` is the one verb that does NOT work on this deployment: it returned HTTP 500 with
        an HTML error page on 2026-08-30. Every other verb returned a well-formed OAI-PMH XML
        document.
      parameters:
        - name: verb
          in: query
          required: true
          description: The OAI-PMH verb to execute.
          schema:
            type: string
            enum:
              - Identify
              - ListMetadataFormats
              - ListSets
              - ListIdentifiers
              - ListRecords
              - GetRecord
          examples:
            listSets:
              value: ListSets
        - name: metadataPrefix
          in: query
          required: false
          description: |-
            Metadata format. Required for `ListIdentifiers`, `ListRecords` and `GetRecord`.
            Seven prefixes were observed as supported.
          schema:
            type: string
            enum: [mods, qdc, oai_dc, oai_cerif_openaire, xmetadiss, nl_didl, uketd_dc]
        - name: identifier
          in: query
          required: false
          description: OAI identifier of a single record. Required for `GetRecord`.
          schema:
            type: string
            examples:
              - oai:research-information.bris.ac.uk:openaire_cris_publications/8f9e7938-b6d4-4aa4-8a5e-6acccbe922a9
        - name: set
          in: query
          required: false
          description: |-
            Set to restrict a selective harvest to. 3,878 sets were observed. An unsupported value
            returns `badArgument`, not `noSetHierarchy`.
          schema:
            type: string
            examples:
              - openaire_cris_publications
              - publications:withFiles
        - name: from
          in: query
          required: false
          description: Lower bound of the datestamp range for selective harvesting.
          schema:
            type: string
            examples: ['2025-01-01T00:00:00Z']
        - name: until
          in: query
          required: false
          description: Upper bound of the datestamp range for selective harvesting.
          schema:
            type: string
            examples: ['2026-01-01T00:00:00Z']
        - name: resumptionToken
          in: query
          required: false
          description: |-
            Flow-control token from a previous incomplete list. Exclusive — combining it with
            `metadataPrefix` returns `badArgument` ("resumptionToken is exclusive!").
          schema:
            type: string
            examples: ['oai_dc/590974/496378582/100/0/641556/x/x/x']
      responses:
        '200':
          description: |-
            An OAI-PMH 2.0 XML response. Protocol-level failures are ALSO returned as 200 with an
            `<error code="...">` element — read the body, not the status.
          content:
            text/xml:
              schema:
                type: string
                contentMediaType: text/xml
              examples:
                listSets:
                  summary: ListSets (observed 2026-08-30)
                  externalValue: https://research-information.bris.ac.uk/ws/oai?verb=ListSets
                badVerb:
                  summary: Protocol error carried inside a 200
                  externalValue: https://research-information.bris.ac.uk/ws/oai?verb=Bogus
        '500':
          description: |-
            Observed for `?verb=Identify` only. Returns a `text/html` Pure error page titled
            "500 Internal server error", not an OAI-PMH document.
          content:
            text/html:
              schema:
                type: string