QU Press Open Journal System OAI-PMH API

openapi: 3.1.0
info:
  title: QU Press Open Journal System OAI-PMH API
  version: '2.0'
  summary: OAI-PMH 2.0 harvesting interface for Qatar University Press's self-hosted journal platform.
  description: |
    Qatar University Press runs its own Open Journal Systems installation (PKP OJS 3.3.0.7) at
    `journals.qu.edu.qa`, on Qatar University's own network. It publishes eight journals plus a
    site-wide index, and exposes an anonymous OAI-PMH 2.0 endpoint both site-wide and per
    journal. The site-wide endpoint self-identifies as `repositoryName: "QU Press Open Journal
    System"`, `adminEmail: mjaberi@qu.edu.qa`, `earliestDatestamp: 2017-12-26T04:51:23Z`,
    `deletedRecord: persistent`, `granularity: YYYY-MM-DDThh:mm:ssZ`, with gzip and deflate
    compression declared. `ListSets` returns 100 sets — one per journal plus per-section
    subsets in English and Arabic. `ListIdentifiers` reports `completeListSize="3186"`.

    This is the profile's clearest institution-operated contract in the scholarly-publishing
    class: `journals.qu.edu.qa` resolves to 185.37.108.12 in netname QUNET, "Qatar University"
    (RIPE), with no CNAME onto a hosting platform, on a `C=QA, L=Doha, O=Qatar University`
    certificate. Compare QSpace, whose hostname is equally Qatar University's but which CNAMEs
    to `qataru.cname.openrepository.com` — a hosted DSpace service — and is therefore recorded
    in this repository as a tenant relationship rather than an institution contract.

    This document is NOT published by Qatar University. It was written by API Evangelist by
    calling the live endpoint on 2026-09-01 and describing only observed behaviour.

    THREE VERIFIED DEFECTS, all Qatar University Press's to fix:
      1. The endpoint emits OAI identifiers it will not accept back. `ListIdentifiers` returns
         `oai:ojs.pkp.sfu.ca:article/11` — the PKP shipped default — while `Identify` declares
         `repositoryIdentifier: ojs.journals.qu.edu.qa`. Feeding an emitted identifier straight
         into `GetRecord` returns `badArgument: "Identifier is not in a valid format"`. Round-trip
         harvesting is broken, and the emitted namespace collides with every other unconfigured
         OJS installation in the world.
      2. TLS chain — the host serves its `O=Qatar University, CN=*.qu.edu.qa` DigiCert leaf
         without the intermediate CA, so a default OpenSSL-based harvester fails with
         `unable to verify the first certificate`. This defeats exactly the automated clients
         OAI-PMH exists to serve.
      3. The adjacent OJS REST API at `/index.php/{journal}/api/v1/` returns 403 to the public,
         so OAI-PMH is the only machine-readable route into this content.
  contact:
    name: Qatar University Press
    email: mjaberi@qu.edu.qa
    url: https://journals.qu.edu.qa/
  x-provenance:
    generated: '2026-09-01'
    method: derived
    source: >-
      Derived from live probes on 2026-09-01 of https://journals.qu.edu.qa/index.php/index/oai —
      verb=Identify (200, OJS 3.3.0.7), verb=ListSets (200, 100 setSpec entries),
      verb=ListMetadataFormats (200, four formats), verb=ListIdentifiers&metadataPrefix=oai_dc
      (200, completeListSize 3186), verb=GetRecord with an emitted identifier (200 carrying
      error badArgument), verb=ListRecords with no metadataPrefix (200 carrying error
      badArgument), verb=Nope (200 carrying error badVerb) — plus verb=Identify against each of
      the eight journal-scoped endpoints, and 403 responses from
      /index.php/jes/api/v1/issues and /contexts. Captured responses are stored under examples/.
    x-operator: institution
    x-operator-basis: >-
      journals.qu.edu.qa resolves to 185.37.108.12, netname QUNET "Qatar University" (RIPE,
      country QA), with no CNAME. TLS subject C=QA, L=Doha, O=Qatar University, CN=*.qu.edu.qa.
      OJS is open-source software from the Public Knowledge Project that Qatar University Press
      self-hosts and operates; the journals, editorial workflow and content are its own.
servers:
  - url: https://journals.qu.edu.qa/index.php
    description: QU Press Open Journal Systems 3.3.0.7 (Qatar University Press)
tags:
  - name: OAI-PMH
    description: The six OAI-PMH 2.0 protocol verbs, site-wide and per journal.
paths:
  /index/oai:
    get:
      tags: [OAI-PMH]
      operationId: oaiRequestAllJournals
      summary: Issue an OAI-PMH 2.0 request across every QU Press journal
      description: >-
        Site-wide OAI-PMH endpoint. Always answers HTTP 200 with `text/xml`; protocol failures
        are reported as an `<error code="...">` element inside the body, never as a non-2xx
        status. A client that branches on the HTTP status alone will read every malformed
        request as an empty success.
      parameters:
        - $ref: '#/components/parameters/Verb'
        - $ref: '#/components/parameters/MetadataPrefix'
        - $ref: '#/components/parameters/Identifier'
        - $ref: '#/components/parameters/Set'
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/Until'
        - $ref: '#/components/parameters/ResumptionToken'
      responses:
        '200':
          description: OAI-PMH XML response, carrying either a payload or an `<error>` element.
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/OaiPmhResponse'
              examples:
                identify:
                  summary: Identify — repository self-description (observed 2026-09-01)
                  externalValue: ../examples/qatar-qupress-oai-identify.xml
                listIdentifiers:
                  summary: 'ListIdentifiers — completeListSize 3186 (observed 2026-09-01)'
                  externalValue: ../examples/qatar-qupress-oai-listidentifiers.xml
                listMetadataFormats:
                  summary: ListMetadataFormats — four supported formats (observed 2026-09-01)
                  externalValue: ../examples/qatar-qupress-oai-listmetadataformats.xml
                getRecordRejectsOwnIdentifier:
                  summary: >-
                    GetRecord with an identifier this endpoint itself emitted — returns
                    badArgument "Identifier is not in a valid format" (observed 2026-09-01)
                  externalValue: ../examples/qatar-qupress-oai-getrecord.xml
                badArgument:
                  summary: 'Error: ListRecords with no metadataPrefix, returned with HTTP 200'
                  externalValue: ../examples/qatar-qupress-oai-error-badargument.xml
                badVerb:
                  summary: 'Error: illegal verb, returned with HTTP 200'
                  externalValue: ../examples/qatar-qupress-oai-error-badverb.xml
  /{journal}/oai:
    get:
      tags: [OAI-PMH]
      operationId: oaiRequestSingleJournal
      summary: Issue an OAI-PMH 2.0 request scoped to one journal
      description: >-
        Per-journal OAI-PMH endpoint. Each journal reports its own `repositoryName` while
        sharing the site-wide `repositoryIdentifier` of `ojs.journals.qu.edu.qa`. All eight
        were confirmed live on 2026-09-01.
      parameters:
        - name: journal
          in: path
          required: true
          description: |
            Journal path identifier as used in the OJS URL. Confirmed values and the
            `repositoryName` each returns:
              * `jes` — Journal of Educational Sciences – Qatar University
              * `sharia` — Journal of College of Sharia and Islamic Studies
              * `tajseer` — Tajseer Journal
              * `IRL` — International Review of Law
              * `SBE` — Studies in Business and Economics
              * `ANDD` — Academic Network for Development Dialogue (ANDD) Paper Series
              * `ANSQ` — ANSAQ Journal
              * `CIC` — Proceedings of the International Conference on Civil Infrastructure and Construction
          schema:
            type: string
            enum: [jes, sharia, tajseer, IRL, SBE, ANDD, ANSQ, CIC]
          example: jes
        - $ref: '#/components/parameters/Verb'
        - $ref: '#/components/parameters/MetadataPrefix'
        - $ref: '#/components/parameters/Identifier'
        - $ref: '#/components/parameters/Set'
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/Until'
        - $ref: '#/components/parameters/ResumptionToken'
      responses:
        '200':
          description: OAI-PMH XML response scoped to the named journal.
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/OaiPmhResponse'
components:
  parameters:
    Verb:
      name: verb
      in: query
      required: true
      description: The OAI-PMH verb to execute.
      schema:
        type: string
        enum: [Identify, ListMetadataFormats, ListSets, ListIdentifiers, ListRecords, GetRecord]
      example: Identify
    MetadataPrefix:
      name: metadataPrefix
      in: query
      required: false
      description: >-
        Dissemination format. Required for ListIdentifiers, ListRecords and GetRecord.
        ListMetadataFormats declares four.
      schema:
        type: string
        enum: [oai_dc, oai_marc, marcxml, rfc1807]
      example: oai_dc
    Identifier:
      name: identifier
      in: query
      required: false
      description: >-
        OAI identifier of a single record. Required for GetRecord. The repository's Identify
        response declares the form `oai:ojs.journals.qu.edu.qa:article/<id>`, but the records
        it actually emits carry `oai:ojs.pkp.sfu.ca:article/<id>` and GetRecord rejects that
        form with badArgument. Neither form was observed to succeed; see the defect note in
        `info.description`.
      schema:
        type: string
      example: 'oai:ojs.journals.qu.edu.qa:article/11'
    Set:
      name: set
      in: query
      required: false
      description: >-
        One of the 100 sets ListSets returns — a journal (`sharia`) or a journal section
        (`sharia:ART`), with `_ar` suffixes marking Arabic-language sections.
      schema:
        type: string
      example: 'sharia:ART'
    From:
      name: from
      in: query
      required: false
      description: Lower bound on record datestamp, at the declared granularity.
      schema: { type: string, format: date-time }
      example: '2025-01-01T00:00:00Z'
    Until:
      name: until
      in: query
      required: false
      description: Upper bound on record datestamp, at the declared granularity.
      schema: { type: string, format: date-time }
      example: '2025-12-31T23:59:59Z'
    ResumptionToken:
      name: resumptionToken
      in: query
      required: false
      description: Continuation token from a previous incomplete list response.
      schema: { type: string }
  schemas:
    OaiPmhResponse:
      type: object
      description: >-
        Root `OAI-PMH` element in namespace http://www.openarchives.org/OAI/2.0/. Described
        structurally; the authoritative schema is the OAI-PMH 2.0 XSD at
        http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd.
      properties:
        responseDate: { type: string, format: date-time }
        request: { type: string, format: uri }
        error: { $ref: '#/components/schemas/OaiPmhError' }
      additionalProperties: true
    OaiPmhError:
      type: object
      description: OAI-PMH protocol error, carried in an HTTP 200 response body.
      properties:
        code:
          type: string
          enum: [badVerb, badArgument, badResumptionToken, cannotDisseminateFormat, idDoesNotExist, noRecordsMatch, noMetadataFormats, noSetHierarchy]
        message: { type: string }
      required: [code]
security: []