persons-v1.yaml

openapi: 3.0.2
info:
  title: Persons API
  description: |-
    The Persons REST API provides enriched information about persons (from Wikidata, Metagrid, DNB Entityfacts, beacon.findbuch). The API also provides lists of people from specific data sources with links to the corresponding person pages.
    
    ➜ [OAS 3 Swagger Documentation](https://eth-library.github.io/apiplatform-swagger/persons/v1/)
    
  version: '1.0.1'
  termsOfService: https://developer.library.ethz.ch/terms
  contact:
    name: API Management ETH Library
    email: api@library.ethz.ch
    url: https://library.ethz.ch
  license:
    url: https://developer.library.ethz.ch/terms
    name: Bibliographic metadata that are not specifically marked are free for general use (Public Domain). Documents, images or other digital objects linked in metadata may be subject to other copyright restrictions. Whenever possible, the licence of the referenced digital objects is indicated in the metadata. In case of doubt, the licence can be inquired at api@library.ethz.ch.
servers:
  - url: https://api.library.ethz.ch/persons/v1/
    description: Production
paths:
  /{code}:
    get:
      tags:
        - List of persons
      description: |- 
        Provides lists of persons from a specific data resource pool with links to correspondig person pages.
        
        Data resource pools and their codes:
        
        | Data resource pool                            | Code        |
        | --------------------------------------------- | ------------|
        | Hochschularchiv (HSA)                         | hsa         |     
        | E-Pics Bildarchiv (BA)                        | ba          |     
        | e-rara                                        | erara       |     
        | Max Frisch-Archiv (MFA)                       | mfa         |  
        | HSA + BA + e-rara + MFA                       | sar         |     
               

      parameters:
        - name: code
          schema:
            type: string
          in: path
          required: true
          description: Code of data resource pool
          examples:
            Hochschularchiv:
              value: hsa
      responses:
        '200':
          description: Returns a list of persons
          content:
            application/json: {}
  /enrichment:
    get:
      tags:
        - Information about a person
      description: |-
        Returns enriched information about a person (from wikidata, Metagrid, DNB Entytyfacts, beacon.findbuch) by wikidata QID or GND ID.

      parameters:
        - name: qid
          schema:
            type: string
          in: query
          required: false
          description: Wikidata QID
          example: Q115835
        - name: gnd
          schema:
            type: string
          in: query
          required: false
          description: GND ID
          example: 120179881
      responses:
        '200':
          description: Returns a person
          content:
            application/json: {}
        '404':
          description: there is no person for this QID
          content:
            text/html: {}
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: apikey
security:
  - ApiKeyAuth: []
externalDocs:
  description: OAS 3 Swagger Documentation
  url: https://apisdocs.library.ethz.ch/persons/v1/