Preservation Catalog HTTP API

openapi: 3.0.0
info:
  description: Preservation Catalog HTTP API
  version: 1.0.0
  title: Preservation Catalog HTTP API
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
servers:
  - url: 'https://preservation-catalog-{env}-01.stanford.edu'
    description: Production service
    variables:
      env:
        default: prod
  - url: 'https://preservation-catalog-{env}-01.stanford.edu'
    description: Staging service
    variables:
      env:
        default: stage
  - url: 'https://preservation-catalog-{env}-01.stanford.edu'
    description: QA service
    variables:
      env:
        default: qa
tags:
  - name: catalog
    description: Add and update Moabs in the catalog
  - name: objects
    description: Preserved Objects
paths:
  /v1/catalog:
    post:
      tags:
        - catalog
      summary: Add a new Moab to the catalog for an existing object
      responses:
        '201':
          description: Created new Moab
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditResultsResponse'
        '409':
          description: Conflict - Moab already exists
        '406':
          description: Invalid arguments passed
        '500':
          description: Internal server error
      requestBody:
        $ref: '#/components/requestBodies/CatalogOptionsWithDruid'
  /v1/catalog/{druid}:
    put:
      tags:
        - catalog
      summary: Update a Moab for an existing object in the catalog for a new version
      responses:
        '200':
          description: Updated Moab
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditResultsResponse'
        '404':
          description: Moab not found
        '406':
          description: Invalid arguments passed
        '400':
          description: Moab version less than what is in catalog
        '500':
          description: Internal server error
      parameters:
        - name: druid
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Druid'
      requestBody:
        $ref: '#/components/requestBodies/CatalogOptions'
    patch:
      tags:
        - catalog
      summary: Update a Moab for an existing object in the catalog for a new version
      responses:
        '200':
          description: Updated Moab
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditResultsResponse'
        '404':
          description: Moab not found
        '406':
          description: Invalid arguments passed
        '400':
          description: Moab version less than what is in catalog
        '500':
          description: Internal server error
      parameters:
        - name: druid
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Druid'
      requestBody:
        $ref: '#/components/requestBodies/CatalogOptions'
  /v1/objects/{id}:
    get:
      tags:
        - objects
      summary: Render a single PreservedObject model as JSON
      responses:
        '200':
          description: Preserved object found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreservedObject'
        '404':
          description: Preserved object not found
      parameters:
        - name: id
          in: path
          required: true
          example: 'druid:bc123df4567.json'
          schema:
            $ref: '#/components/schemas/DruidWithOptionalFormat'
  /v1/objects/{id}/validate_moab:
    get:
      tags:
        - objects
      summary: Starts a validate moab job, which does a validation of the on disk Moab, without reference to the preservation-catalog basis
      responses:
        '200':
          description: Job queued
        '400':
          description: Bad request (e.g., malformed druid)
        '423':
          description: Failed to enqueue the job, likely because it is a duplicate of a job already waiting in the queue. Caller may retry later if appropriate.
      parameters:
        - name: id
          in: path
          required: true
          example: 'druid:bc123df4567'
          schema:
            $ref: '#/components/schemas/Druid'
        - name: lane-id
          in: query
          schema:
            description: Lane for prioritizing the work
            type: string
            enum:
              - "default"
              - "low"
              - "high"
            default: "default"
  /v1/objects/{id}/checksum:
    get:
      tags:
        - objects
      summary: Show the checksums and filesizes for a single object
      responses:
        '200':
          description: Object found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChecksumsForObject'
        '400':
          description: Bad request (e.g., malformed druid)
        '404':
          description: Object not found
      parameters:
        - name: id
          in: path
          required: true
          example: 'druid:bc123df4567'
          schema:
            $ref: '#/components/schemas/Druid'
  /v1/objects/{id}/file:
    get:
      tags:
        - objects
      summary: Returns a specific content, metadata, or manifest file for the object.
      responses:
        '200':
          description: OK, returns a file (of whatever type, thus not validated here)
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          description: Version parameter not positive integer or other problem with request params
        '404':
          description: Object or file or version not found
      parameters:
        - name: id
          in: path
          required: true
          example: 'druid:bc123df4567'
          schema:
            $ref: '#/components/schemas/Druid'
        - name: filepath
          description: filepath relative to given `category` query argument, which is a directory in the Moab
          in: query
          required: true
          example: 'manifestInventory.xml'
          schema:
            type: string
        - name: category
          description: category of file to return
          in: query
          required: true
          example: 'manifest'
          schema:
            type: string
            enum:
              - content
              - manifest
              - metadata
        - name: version
          in: query
          required: false
          example: '9'
          schema:
            type: string
            nullable: true
  /v1/objects/{id}/content_diff:
    post:
      tags:
        - objects
      summary:
        Retrieves Moab::FileInventoryDifference model from comparison of passed contentMetadata.xml with latest (or specified) version
        in Moab for all files (default) or a specified subset.
      responses:
        '200':
          description: OK
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ContentDiff'
        '400':
          description: Version parameter not a positive integer or parameter error raised
        '500':
          description: Unable to get content diff
      parameters:
        - name: id
          in: path
          required: true
          example: 'druid:bc123df4567'
          schema:
            $ref: '#/components/schemas/Druid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content_metadata:
                  type: string
                  description: an XML representation of content metadata
                version:
                  example: '9'
                  type: string
                  nullable: true
                subset:
                  example: 'publish'
                  description: "subset of files to diff (default: 'all')"
                  type: string
                  nullable: true
                  enum:
                    - all
                    - shelve
                    - publish
                    - preserve
              required:
                - content_metadata
components:
  requestBodies:
    CatalogOptions:
      description: Common options for PUT/POST/PATCH operations to the catalog controller
      required: true
      content:
        application/x-www-form-urlencoded:
          schema:
            $ref: '#/components/schemas/CatalogOptions'
        application/json:
          schema:
            $ref: '#/components/schemas/CatalogOptions'
    CatalogOptionsWithDruid:
      description: Common options (plus druid) for PUT/POST/PATCH operations to the catalog controller
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CatalogOptionsWithDruid'
        application/x-www-form-urlencoded:
          schema:
            $ref: '#/components/schemas/CatalogOptionsWithDruid'
  schemas:
    Druid:
      description: Digital Repository Unique Identifier (bare or prefixed)
      type: string
      pattern: '^(druid:)?[b-df-hjkmnp-tv-z]{2}[0-9]{3}[b-df-hjkmnp-tv-z]{2}[0-9]{4}$'
      example: 'druid:bc123df4567'
    DruidWithOptionalFormat:
      description: Digital Repository Unique Identifier (bare or prefixed), with a file extension
      type: string
      pattern: '^(druid:)?[b-df-hjkmnp-tv-z]{2}[0-9]{3}[b-df-hjkmnp-tv-z]{2}[0-9]{4}(\.json)?$'
      example: 'druid:bc123df4567.json'
    CatalogOptions:
      description: Options for catalog controller endpoint
      type: object
      properties:
        incoming_version:
          description: Version of the object
          type: integer
        incoming_size:
          description: Size in bytes of the object on disk
          type: integer
        storage_location:
          description: Storage root where the moab object is located (must correspond to a real MoabStorageRoot)
          type: string
        checksums_validated:
          description: If the checksums for the moab object have previously been validated by caller (boolean/int as string)
          oneOf:
            - type: boolean
            - type: string
              enum:
                - 'true'
                - 'True'
                - 'TRUE'
                - 'nil'
                - '1'
                - 'on'
                - 'false'
                - 'False'
                - 'FALSE'
      required:
        - incoming_version
        - incoming_size
        - storage_location
    CatalogOptionsWithDruid:
      allOf:
        - $ref: '#/components/schemas/CatalogOptions'
        - type: object
          properties:
            druid:
              $ref: '#/components/schemas/Druid'
          required:
            - druid
    ContentDiff:
      description: A diff between given and existing content metadata (XML)
      type: object
      properties:
        objectId:
          $ref: '#/components/schemas/Druid'
        differenceCount:
          type: string
          example: '2'
        basis:
          type: string
          example: 'v1-contentMetadata-all'
        other:
          type: string
          example: 'new-contentMetadata-all'
        reportDatetime:
          type: string
          format: date-time
        fileGroupDifference:
          type: object
          properties:
            groupId:
              type: string
            differenceCount:
              type: string
            identical:
              type: string
            copyadded:
              type: string
            copydeleted:
              type: string
            renamed:
              type: string
            modified:
              type: string
            added:
              type: string
            deleted:
              type: string
            subset:
              type: array
              items:
                type: object
                properties:
                  change:
                    type: string
                  count:
                    type: string
                  file:
                    type: array
                    items:
                      type: object
                      properties:
                        change:
                          type: string
                        basisPath:
                          type: string
                        otherPath:
                          type: string
                        fileSignature:
                          type: object
                          properties:
                            size:
                              type: string
                            md5:
                              type: string
                            sha1:
                              type: string
                            sha256:
                              type: string
      required: # really not sure how much of the above is required or not
        - object_id
        - difference_count
        - basis
        - other
        - report_datetime
    ChecksumsForObject:
      description: A representation of all files and checksums for a single object
      type: array
      items:
        type: object
        properties:
          filename:
            type: string
            example: 'eric-smith-dissertation.pdf'
          md5:
            type: string
            example: 'aead2f6f734355c59af2d5b2689e4fb3'
          sha1:
            type: string
            example: '22dc6464e25dc9a7d600b1de6e3848bf63970595'
          sha256:
            type: string
            example: 'e49957d53fb2a46e3652f4d399bd14d019600cf496b98d11ebcdf2d10a8ffd2f'
          filesize:
            type: integer
            example: 1000217
        required:
          - filename
          - md5
          - sha1
          - sha256
          - filesize
    PreservedObject:
      description: A preserved object instance
      type: object
      properties:
        druid:
          $ref: '#/components/schemas/Druid'
        current_version:
          type: integer
          example: 13
        ok_on_local_storage:
          description: True if the files for the object on local storage (as represented by the  MoabRecord) are not in an error state
          type: boolean
      required:
        - druid
        - current_version
        - ok_on_local_storage
    AuditResult:
      description: A single audit result
      type: object
    AuditResultsResponse:
      description: Audit results response
      type: object
      properties:
        druid:
          $ref: '#/components/schemas/Druid'
        result_array:
          type: array
          items:
            $ref: '#/components/schemas/AuditResult'
      required:
        - druid
        - result_array
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []