openapi: 3.0.2
info:
  description: Documentation of the PHAIDRA API.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: PHAIDRA datastream oai-pmh API
  version: '3.0'
servers:
- description: API endpoint
  url: https://phaidra.unipd.it/api
tags:
- description: Look at the [OAI-PMH protocol](https://www.openarchives.org/pmh) used in this endpoint
  name: oai-pmh
paths:
  /oai:
    get:
      parameters:
      - description: See [the OAI-PMH protocol](https://www.openarchives.org/pmh/)
        examples:
          GetRecord:
            summary: GetRecord
            value: GetRecord
          Identify:
            summary: Identify
            value: Identify
          ListIdentifiers:
            summary: ListIdentifiers
            value: ListIdentifiers
          ListRecords:
            summary: ListRecords
            value: ListRecords
        in: query
        name: verb
        schema:
          type: number
      responses:
        '200':
          content:
            text/xml:
              schema:
                type: string
          description: ''
      summary: OAI-PMH endpoint.
      tags:
      - oai-pmh
    post:
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: See [the OAI-PMH protocol](https://www.openarchives.org/pmh/)
      summary: Same as GET.
      tags:
      - oai-pmh
  /oai/blacklist:
    post:
      description: Ingest TSV with columns `AC-Nummer` and `Identifier Phaidra`, and create records in `oai_records_blacklist` if ac_number/pid not already present. The blacklist is a list of PIDs which should not be included in a particular set in OAI-PMH, e.g. because the harvester gets those objects by other means (avoids duplicity).
      parameters:
      - description: Optional sets (comma-separated), if not supplied in JSON body.
        in: query
        name: sets
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              sets:
              - phaidra4primo
              tsv: "AC-Nummer\tIdentifier Phaidra\nAC00001880\to:2045295"
            schema:
              properties:
                sets:
                  items:
                    type: string
                  type: array
                tsv:
                  type: string
              type: object
          text/plain:
            example: "AC-Nummer\tIdentifier Phaidra\nAC00001880\to:2045295\nAC00003863\to:2040220"
            schema:
              type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  existing:
                    type: integer
                  existing_items:
                    items:
                      type: object
                    type: array
                  inserted:
                    type: integer
                  inserted_items:
                    items:
                      type: object
                    type: array
                  invalid:
                    type: integer
                  invalid_items:
                    items:
                      type: object
                    type: array
                  sets:
                    items:
                      type: string
                    type: array
                  total_rows:
                    type: integer
                type: object
          description: Summary of inserted/existing/invalid rows
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Bad request details
      summary: Add blacklist entries from TSV or JSON payload
      tags:
      - oai-pmh
components:
  securitySchemes:
    basicAuth:
      scheme: basic
      type: http
    tokenAuth:
      in: header
      name: X-XSRF-TOKEN
      type: apiKey