docs.yaml

openapi: 3.0.0
servers:
  - url: http://nih-guid-broker-elb-1813020435.eu-west-1.elb.amazonaws.com/
    x-location: EU
    x-maturity: development
info:
  version: '0.2'
  title: GUID Broker
  description: Global Unique ID Broker part of the NIH Data Commons initiative
  termsOfService: https://www.elsevier.com/legal/elsevier-website-terms-and-conditions
  contact:
    name: Elsevier
    url: https://www.elsevier.com/
    x-role: responsible organization
  x-accessRestriction: none
  x-implementationLanguage: Java
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
tags:
  - name: DataCite
    description: DataCite Broker
  - name: EZID
    description: EZID Broker
paths:
  /broker/doi:
    post:
      tags:
        - DataCite
      summary: >-
        Will create a new DOI, but instead of supplying a complete identifier,
        the client specifies only a partial namespace (shoulder).
      description: ''
      operationId: mintDOI
      responses:
        '201':
          description: Created
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/DigitalObject'
        '400':
          description: Bad request
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
      requestBody:
        $ref: '#/components/requestBodies/mintDOIBody'
      x-accessRestriction: limited
  '/broker/doi/{identifier}':
    get:
      tags:
        - DataCite
      summary: Returns metadata for a given DOI
      description: ''
      operationId: retriveDOI
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
            pattern: .+
      responses:
        '200':
          description: Success
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/DigitalObject'
        '404':
          description: The resource you were trying to reach is not found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
      x-accessRestriction: none
    put:
      tags:
        - DataCite
      summary: >-
        Will create a new DOI if the specified DOI doesn’t exist. Will not
        update an existing DOI, but will return an error.
      description: ''
      operationId: createDOI
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
            pattern: .+
      responses:
        '201':
          description: Created
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/DigitalObject'
        '400':
          description: Bad request
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
        '404':
          description: The resource you were trying to reach is not found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
      requestBody:
        $ref: '#/components/requestBodies/mintDOIBody'
      x-accessRestriction: limited
    delete:
      tags:
        - DataCite
      summary: 'Delete a doi, note that only reserved identifiers may be deleted'
      description: ''
      operationId: deleteDOI
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
            pattern: .+
      responses:
        '200':
          description: Success
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
      x-accessRestriction: limited
    patch:
      tags:
        - DataCite
      summary: >-
        Will create a new DOI if the specified DOI doesn’t exist. Will not
        update an existing DOI, but will return an error.
      description: ''
      operationId: updateDOI
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
            pattern: .+
      responses:
        '201':
          description: Created
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/DigitalObject'
        '400':
          description: Bad request
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
        '404':
          description: The resource you were trying to reach is not found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
      requestBody:
        $ref: '#/components/requestBodies/mintDOIBody'
      x-accessRestriction: limited
  /broker/minid:
    post:
      tags:
        - EZID
      summary: Create an ark
      description: ''
      operationId: mintARK
      responses:
        '201':
          description: Created
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/DigitalObject'
        '400':
          description: Bad request
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
      requestBody:
        $ref: '#/components/requestBodies/mintDOIBody'
      x-accessRestriction: none
  '/broker/minid/{identifier}':
    get:
      tags:
        - EZID
      summary: Retrieve an ark
      description: ''
      operationId: retriveARK
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
            pattern: .+
      responses:
        '200':
          description: Success
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/DigitalObject'
        '404':
          description: The resource you were trying to reach is not found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
      x-accessRestriction: limited
    put:
      tags:
        - EZID
      summary: Creates an ark
      description: ''
      operationId: createARK
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
            pattern: .+
      responses:
        '201':
          description: Created
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/DigitalObject'
        '400':
          description: Bad request
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
        '404':
          description: The resource you were trying to reach is not found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
      requestBody:
        $ref: '#/components/requestBodies/mintDOIBody'
      x-accessRestriction: limited
    delete:
      tags:
        - EZID
      summary: Delete an ark
      description: ''
      operationId: deleteARK
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
            pattern: .+
      responses:
        '200':
          description: Success
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
      x-accessRestriction: limited
    patch:
      tags:
        - EZID
      summary: Updates an ark
      description: ''
      operationId: updateARK
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
            pattern: .+
      responses:
        '201':
          description: Created
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/DigitalObject'
        '400':
          description: Bad request
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
        '404':
          description: The resource you were trying to reach is not found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/BrokerResponse'
      requestBody:
        $ref: '#/components/requestBodies/mintDOIBody'
      x-accessRestriction: limited
components:
  requestBodies:
    mintDOIBody:
      content:
        application/json;charset=UTF-8:
          schema:
            type: string
  schemas:
    Wrapper:
      type: object
      properties:
        name:
          type: string
        license:
          type: string
        contributors:
          type: array
          items:
            type: string
        language:
          $ref: '#/components/schemas/Language'
    BrokerResponse:
      type: object
      properties:
        message:
          type: string
        statusCode:
          type: integer
          format: int32
    Language:
      type: object
      properties:
        version:
          type: string
        name:
          type: string
    Toolkit:
      type: object
      properties:
        name:
          type: string
        version:
          type: string
        license:
          type: string
        author:
          type: string
    DigitalObject:
      type: object
      properties:
        identifier:
          type: object
        url:
          type: object
        contentUrl:
          type: object
        includedInDataCatalog:
          type: object
          additionalProperties:
            type: object
        name:
          type: string
        toolAuthor:
          type: string
        categories:
          type: array
          items:
            type: string
        toolkit:
          $ref: '#/components/schemas/Toolkit'
        wrapper:
          $ref: '#/components/schemas/Wrapper'
        author:
          type: object
        '@context':
          type: string
          readOnly: true
        '@id':
          type: string
        '@type':
          type: string
          readOnly: true
          enum:
            - DATASET
            - SOFTWARE_SOURCE_CODE
            - CREATIVE_WORK
            - COLLECTION
x-externalResources:
  - x-url: https://www.datacite.org/
    x-type: website
    x-description: Authority used to handle DOIs
  - x-url: https://ezid.cdlib.org/
    x-type: website
    x-description: Authority used to handle ARKs