swagger: "2.0"
schemes:
  - http
host: localhost:8080
basePath: /exist/apps/WeGA-WebApp/api/v1
info:
  description: ⚠️<b>DEPRECATION WARNING</b>⚠️<br/>This version of the WeGA API specification is outdated and superseded by [version 1.1.0](https://weber-gesamtausgabe.de/api/v1/openapi.json).  <br/> <br/> For feedback or requests about this API please contact stadler@weber-gesamtausgabe.de or start the discussion at https://github.com/Edirom/WeGA-WebApp
  title: WeGA API
  version: 1.0.0
  x-apisguru-categories:
    - open_data
  x-logo:
    backgroundColor: "#FFFFFF"
    url: https://web.archive.org/web/20180313153846im_/https://weber-gesamtausgabe.de/resources/img/logo_weber.png
  x-origin:
    - format: swagger
      url: https://weber-gesamtausgabe.de/api/v1/swagger.json
      version: "2.0"
  x-providerName: weber-gesamtausgabe.de
parameters:
  docTypeParam:
    collectionFormat: csv
    description: The WeGA document type
    in: query
    items:
      enum:
        - biblio
        - diaries
        - documents
        - letters
        - news
        - orgs
        - persons
        - places
        - thematicCommentaries
        - var
        - works
        - writings
      type: string
    name: docType
    type: array
  docTypeRequiredParam:
    collectionFormat: csv
    description: The WeGA document type
    in: query
    items:
      enum:
        - biblio
        - diaries
        - documents
        - letters
        - news
        - orgs
        - persons
        - places
        - thematicCommentaries
        - var
        - works
        - writings
      type: string
    name: docType
    required: true
    type: array
  fromDateParam:
    description: The earliest date
    format: date
    in: query
    name: fromDate
    type: string
  limitParam:
    default: 10
    description: Number of items to retrieve (200 max)
    format: int32
    in: query
    maximum: 200
    name: limit
    type: integer
  offsetParam:
    default: 1
    description: Position of first item to retrieve (starting from 1)
    format: int32
    in: query
    minimum: 1
    name: offset
    type: integer
  qParam:
    description: The query string
    in: query
    name: q
    type: string
  toDateParam:
    description: The latest date
    format: date
    in: query
    name: toDate
    type: string
tags:
  - description: Access to the documents of the WeGA digital edition
    name: Documents
  - description: Access to search functions of the WeGA digital edition
    name: Search
  - description: Access to encoding features
    name: Code Samples
  - description: Access to application settings
    name: Application
  - description: Access to facets for filtering result sets
    name: Facets
paths:
  /application/newID:
    get:
      description: ""
      parameters:
        - $ref: "#/parameters/docTypeRequiredParam"
      produces:
        - application/json
      responses:
        "200":
          description: A single object with a fresh WeGA ID
          schema:
            properties:
              docID:
                description: The WeGA ID
                pattern: ^A[A-F0-9]{6}$
                type: string
              docType:
                description: The WeGA document type
                type: string
            type: object
        "403":
          description: The creation of new IDs is only available in the development environment
          schema:
            properties:
              code:
                default: 403
                format: int32
                type: integer
              message:
                type: string
            type: object
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Create a new WeGA ID
      tags:
        - Application
  /application/status:
    get:
      description: ""
      produces:
        - application/json
      responses:
        "200":
          description: Healthy – A single object with status information
          schema:
            properties:
              deployment:
                description: The datetime of the deployment of the WeGA-WebApp
                format: date-time
                type: string
              status:
                default: healthy
                description: Status (healthy|unhealthy) of the currently running WeGA-WebApp
                type: string
              svnRevision:
                description: The Subversion revision of the currently installed WeGA-data
                type: integer
              version:
                pattern: ^\d+\.\d+\.\d+$
                type: string
            type: object
        "500":
          description: Unhealthy – A single object with status information
          schema:
            properties:
              deployment:
                description: The datetime of the deployment of the WeGA-WebApp
                format: date-time
                type: string
              status:
                default: unhealthy
                description: Status (healthy|unhealthy) of the currently running WeGA-WebApp
                type: string
              svnRevision:
                description: The Subversion revision of the currently installed WeGA-data
                type: integer
              version:
                pattern: ^\d+\.\d+\.\d+$
                type: string
            type: object
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Get status information about the running WeGA-WebApp
      tags:
        - Application
  "/code/findByElement/{element}":
    get:
      description: ""
      parameters:
        - description: The XML element to search for
          in: path
          name: element
          required: true
          type: string
        - default: http://www.tei-c.org/ns/1.0
          description: The element namespace. Defaults to the TEI namespace
          in: query
          name: namespace
          required: false
          type: string
        - $ref: "#/parameters/docTypeParam"
        - $ref: "#/parameters/offsetParam"
        - $ref: "#/parameters/limitParam"
      produces:
        - application/json
      responses:
        "200":
          description: An array of documents
          headers:
            totalrecordcount:
              description: The total size of the result set
              type: integer
          schema:
            items:
              $ref: "#/definitions/CodeSample"
            type: array
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Finds code samples by XML element
      tags:
        - Code Samples
  /documents:
    get:
      description: |
        The Documents endpoint returns a list of all documents from the WeGA digital edition.
      parameters:
        - $ref: "#/parameters/docTypeParam"
        - $ref: "#/parameters/offsetParam"
        - $ref: "#/parameters/limitParam"
      produces:
        - application/json
      responses:
        "200":
          description: An array of documents
          headers:
            totalrecordcount:
              description: The total size of the result set
              type: integer
          schema:
            items:
              $ref: "#/definitions/Document"
            type: array
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Lists all documents
      tags:
        - Documents
  "/documents/findByAuthor/{authorID}":
    get:
      description: |
        This endpoint returns a list of documents by a given author – optionally filtered by document type 
      parameters:
        - default: A002068
          description: |
            The author ID to search for. Accepted ID formats are WeGA, e.g. A002068 or http://weber-gesamtausgabe.de/A002068, VIAF, e.g. http://viaf.org/viaf/14959938, or  GND, e.g. http://d-nb.info/gnd/118629662
          in: path
          name: authorID
          required: true
          type: string
        - $ref: "#/parameters/docTypeParam"
        - $ref: "#/parameters/offsetParam"
        - $ref: "#/parameters/limitParam"
      produces:
        - application/json
      responses:
        "200":
          description: An array of documents
          headers:
            totalrecordcount:
              description: The total size of the result set
              type: integer
          schema:
            items:
              $ref: "#/definitions/Document"
            type: array
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Finds documents by author
      tags:
        - Documents
  /documents/findByDate:
    get:
      description: |
        This endpoint returns a list of documents related to the given date – optionally filtered by document type. 
      parameters:
        - default: 1786-11-18
          description: The min date to search for
          format: date
          in: query
          name: fromDate
          required: true
          type: string
        - description: The max date to search for
          format: date
          in: query
          name: toDate
          required: false
          type: string
        - $ref: "#/parameters/docTypeParam"
        - $ref: "#/parameters/offsetParam"
        - $ref: "#/parameters/limitParam"
      produces:
        - application/json
      responses:
        "200":
          description: An array of documents
          headers:
            totalrecordcount:
              description: The total size of the result set
              type: integer
          schema:
            items:
              $ref: "#/definitions/Document"
            type: array
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Finds documents by date
      tags:
        - Documents
  "/documents/findByMention/{docID}":
    get:
      description: |
        This endpoint returns a list of documents that reference a particular docID – optionally filtered by document type. 
      parameters:
        - default: A002068
          description: |
            The document ID that is to be mentioned. Accepted ID formats are WeGA, e.g. A002068 or http://weber-gesamtausgabe.de/A002068, VIAF, e.g. http://viaf.org/viaf/14959938, or  GND, e.g. http://d-nb.info/gnd/118629662
          in: path
          name: docID
          required: true
          type: string
        - $ref: "#/parameters/docTypeParam"
        - $ref: "#/parameters/offsetParam"
        - $ref: "#/parameters/limitParam"
      produces:
        - application/json
      responses:
        "200":
          description: An array of documents
          headers:
            totalrecordcount:
              description: The total size of the result set
              type: integer
          schema:
            items:
              $ref: "#/definitions/Document"
            type: array
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Finds documents by reference
      tags:
        - Documents
  "/documents/{docID}":
    get:
      description: |
        This endpoint returns documents, indicated by an ID.
         Accepted ID formats are WeGA, e.g. A002068 or http://weber-gesamtausgabe.de/A002068, VIAF, e.g. http://viaf.org/viaf/14959938, or  GND, e.g. http://d-nb.info/gnd/118629662
      parameters:
        - default: A002068
          description: The document identifier to search for
          in: path
          name: docID
          required: true
          type: string
      produces:
        - application/json
      responses:
        "200":
          description: An array of documents
          schema:
            items:
              $ref: "#/definitions/Document"
            type: array
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Returns documents by ID
      tags:
        - Documents
  "/facets/{facet}":
    get:
      description: ""
      parameters:
        - description: The facet to search for
          enum:
            - sender
            - addressee
          in: path
          name: facet
          required: true
          type: string
        - description: The scope of the result set, i.e. 'indices' or a WeGA ID
          in: query
          name: scope
          pattern: ^(indices)|(A[A-F0-9]{6})$
          required: true
          type: string
        - description: The search term to be looked for in the facet's label
          in: query
          name: term
          type: string
        - $ref: "#/parameters/docTypeRequiredParam"
        - $ref: "#/parameters/offsetParam"
        - $ref: "#/parameters/limitParam"
      produces:
        - application/json
      responses:
        "200":
          description: An array of facets
          headers:
            totalrecordcount:
              description: The total size of the result set
              type: integer
          schema:
            items:
              $ref: "#/definitions/Facet"
            type: array
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Returns facets
      tags:
        - Facets
  /search/entity:
    get:
      description: |
        This endpoint returns the search results for an entity's name or title.
      parameters:
        - $ref: "#/parameters/docTypeParam"
        - $ref: "#/parameters/qParam"
        - $ref: "#/parameters/offsetParam"
        - $ref: "#/parameters/limitParam"
      produces:
        - application/json
      responses:
        "200":
          description: An array of documents
          headers:
            totalrecordcount:
              description: The total size of the result set
              type: integer
          schema:
            items:
              $ref: "#/definitions/Document"
            type: array
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Search for a WeGA entity
      tags:
        - Search
definitions:
  CodeSample:
    properties:
      codeSample:
        description: The code snippet
        type: string
      docID:
        description: The WeGA document identifier representing a specific document
        type: string
      uri:
        description: Unique identifier representing a specific document
        type: string
    type: object
  Document:
    properties:
      docID:
        description: The WeGA document identifier representing a specific document
        type: string
      docType:
        description: The WeGA document type
        type: string
      title:
        description: The title of the document
        type: string
      uri:
        description: Unique identifier representing a specific document
        type: string
    type: object
  Error:
    properties:
      code:
        format: int32
        type: integer
      fields:
        type: string
      message:
        type: string
    type: object
  Facet:
    properties:
      frequency:
        description: The sum of occurences of the object for the current result set
        type: integer
      label:
        description: The name or title of the object
        type: string
      value:
        description: the WeGA ID
        pattern: ^A[A-F0-9]{6}$
        type: string
    type: object
