inventory.raml

#%RAML 1.0
title: Inventory API
version: v14.0
protocols: [ HTTP, HTTPS ]
baseUri: http://localhost

documentation:
  - title: "Inventory API"
    content: <b>API for interacting with an inventory of physical resources</b>

types:
  errors: !include raml-util/schemas/errors.schema
  item: !include item.json
  items: !include items.json
  cqlQueryRequestDto: !include CQLQueryRequestDto.json
  holdings: !include holdings-record.json
  instance: !include instance.json
  instances: !include instances.json
  tenantItemPairCollection: !include tenantItemPairCollection.json
  patchRequest: !include patch_request.json

traits:
  language: !include raml-util/traits/language.raml
  pageable: !include raml-util/traits/pageable.raml
  searchable: !include raml-util/traits/searchable.raml
  validate: !include raml-util/traits/validation.raml

resourceTypes:
  collection: !include raml-util/rtypes/collection.raml
  collection-item: !include raml-util/rtypes/item-collection.raml

/inventory:
  /items:
    displayName: Items
    type:
      collection:
        exampleCollection: !include examples/items_get.json
        schemaCollection: items
        schemaItem: item
        exampleItem: !include examples/item_get.json
    get:
      is: [pageable,
          searchable: {description: "using CQL (indexes for item and material type)",
            example: "barcode==\"65345656554\""}
          ]
    post:
    delete:
      is: [searchable: { description: "CQL to select items to delete, use cql.allRecords=1 to delete all", example: "barcode==\"123-0*\"" } ]
      responses:
        204:
          description: "Selected items deleted"
        400:
          description: "Bad request, e.g. malformed query parameter"
          body:
            text/plain:
              example: "query parameter is empty"
        500:
          description: "Internal server error, e.g. due to misconfiguration"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
    /retrieve:
      post:
        is: [ validate ]
        body:
          application/json:
            type: cqlQueryRequestDto
            example:
              strict: false
              value: !include examples/cqlQueryRequestDto.json
        description: |
          Fetch inventory items collection by POST request
    /{itemId}:
      type:
        collection-item:
          exampleItem: !include examples/item_get.json
          schema: item
      get:
      patch:
              description: Partial update of item with given ID
              body:
                application/json:
                  type: patchRequest
                  example: !include examples/patch-request.json
              responses:
                204:
                  description: "Item successfully updated"
                404:
                  description: "Item with a given ID not found"
                  body:
                    text/plain:
                      example: Not found
                400:
                  description: "Bad request, e.g. malformed request body or query parameter."
                  body:
                    text/plain:
                      example: "unable to update instance - malformed JSON"
                409:
                  description: "Optimistic locking version conflict"
                  body:
                    text/plain:
                      example: "version conflict"
                500:
                  description: "Internal server error, e.g. due to misconfiguration"
                  body:
                    text/plain:
                      example: "internal server error, contact administrator"
      /mark-withdrawn:
        post:
          responses:
            201:
              description: "Item has marked as withdrawn"
              body:
                application/json:
                  example: !include examples/item_get.json
                  type: item
            404:
              description: "Item not found"
              body:
                text/plain:
                  example: "Item with such id not found"
            422:
              description: "Validation error"
              body:
                application/json:
                  type: errors
            500:
              description: "Internal server error"
              body:
                text/plain:
                  example: "Internal server error"
      /mark-in-process:
        post:
          responses:
            200:
              description: "Item has marked as in process"
              body:
                application/json:
                  example: !include examples/item_get.json
                  type: item
            404:
              description: "Item not found"
              body:
                text/plain:
                  example: "Item with such id not found"
            422:
              description: "Validation error"
              body:
                application/json:
                  type: errors
            500:
              description: "Internal server error"
              body:
                text/plain:
                  example: "Internal server error"
      /mark-in-process-non-requestable:
        post:
          responses:
            200:
              description: "Item has marked as in process (non requestable)"
              body:
                application/json:
                  example: !include examples/item_get.json
                  type: item
            404:
              description: "Item not found"
              body:
                text/plain:
                  example: "Item with such id not found"
            422:
              description: "Validation error"
              body:
                application/json:
                  type: errors
            500:
              description: "Internal server error"
              body:
                text/plain:
                  example: "Internal server error"
      /mark-intellectual-item:
        post:
          responses:
            200:
              description: "Item has marked as intellectual item"
              body:
                application/json:
                  example: !include examples/item_get.json
                  type: item
            404:
              description: "Item not found"
              body:
                text/plain:
                  example: "Item with such id not found"
            422:
              description: "Validation error"
              body:
                application/json:
                  type: errors
            500:
              description: "Internal server error"
              body:
                text/plain:
                  example: "Internal server error"
      /mark-long-missing:
        post:
          responses:
            200:
              description: "Item has marked as long missing"
              body:
                application/json:
                  example: !include examples/item_get.json
                  type: item
            404:
              description: "Item not found"
              body:
                text/plain:
                  example: "Item with such id not found"
            422:
              description: "Validation error"
              body:
                application/json:
                  type: errors
            500:
              description: "Internal server error"
              body:
                text/plain:
                  example: "Internal server error"
      /mark-missing:
        post:
          responses:
            201:
              description: "Item has marked as missing"
              body:
                application/json:
                  example: !include examples/item_get.json
                  type: item
            404:
              description: "Item not found"
              body:
                text/plain:
                  example: "Item with such id not found"
            422:
              description: "Validation error"
              body:
                application/json:
                  type: errors
            500:
              description: "Internal server error"
              body:
                text/plain:
                  example: "Internal server error"
      /mark-restricted:
        post:
          responses:
            200:
              description: "Item has marked as restricted"
              body:
                application/json:
                  example: !include examples/item_get.json
                  type: item
            404:
              description: "Item not found"
              body:
                text/plain:
                  example: "Item with such id not found"
            422:
              description: "Validation error"
              body:
                application/json:
                  type: errors
            500:
              description: "Internal server error"
              body:
                text/plain:
                  example: "Internal server error"
      /mark-unavailable:
        post:
          responses:
            200:
              description: "Item has marked as unavailable"
              body:
                application/json:
                  example: !include examples/item_get.json
                  type: item
            404:
              description: "Item not found"
              body:
                text/plain:
                  example: "Item with such id not found"
            422:
              description: "Validation error"
              body:
                application/json:
                  type: errors
            500:
              description: "Internal server error"
              body:
                text/plain:
                  example: "Internal server error"
      /mark-unknown:
        post:
          responses:
            200:
              description: "Item has marked as unknown"
              body:
                application/json:
                  example: !include examples/item_get.json
                  type: item
            404:
              description: "Item not found"
              body:
                text/plain:
                  example: "Item with such id not found"
            422:
              description: "Validation error"
              body:
                application/json:
                  type: errors
            500:
              description: "Internal server error"
              body:
                text/plain:
                  example: "Internal server error"
  /items-by-holdings-id:
    displayName: Items, including bound-with Items, by holdingsRecord ID
    type:
      collection:
        exampleCollection: !include examples/items_get.json
        schemaCollection: items
        schemaItem: item
        exampleItem: !include examples/items_get.json
    get:
      is: [pageable: {description: "The default page size is 200. Maximum page size is 10000."},
        searchable: {description: "query by holdings record ID. This is a mandatory query parameter.
       An optional parameter, 'relations', can be passed outside of the query to restrict what
       Items are returned based on their type of relationship with the holdings record.
       Possible values of the 'relations' parameter are: 'onlyBoundWiths', 'onlyBoundWithsSkipDirectlyLinkedItem'",
            example: "holdingsRecordId==\"[UUID]\""}
          ]
  /tenant-items:
    displayName: Fetch items based on tenant IDs
    post:
      body:
        application/json:
          type: tenantItemPairCollection
      responses:
        200:
          description: "Fetched items based on tenant IDs"
          body:
            application/json:
              type: items
  /holdings/{holdingsId}:
    put:
      description: Update Holdings by holdingsId
      is: [validate]
      body:
        application/json:
          type: holdings
          example:
            strict: false
            value: !include examples/holdings_put.json
      responses:
        204:
          description: "Holdings successfully updated"
        404:
          description: "Holdings with a given ID not found"
          body:
            text/plain:
              example: |
                "Holdings not found"
        400:
          description: "Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response."
          body:
            text/plain:
              example: |
                "unable to update Holdings -- malformed JSON at 13:4"
        409:
          description: "Optimistic locking version conflict"
          body:
            text/plain:
              example: "version conflict"
        500:
          description: "Internal server error, e.g. due to misconfiguration"
          body:
            text/plain:
              example: "internal server error, contact administrator"
  /instances:
    displayName: Instances
    type:
      collection:
        exampleCollection: !include  examples/instances_get.json
        schemaCollection: instances
        schemaItem: instance
        exampleItem: !include examples/instance_get.json
    get:
      is: [pageable,
          searchable: {description: "using CQL (indexes for item and material type)",
            example: "title=\"uproot*\""}
          ]
    post:
      is: [validate]
    delete:
      is: [searchable: { description: "CQL to select instances to delete, use cql.allRecords=1 to delete all. Deletes connected marc source records.",
                         example: "hrid==\"in123-0*\"" } ]
      responses:
        204:
          description: "Selected instances deleted"
        400:
          description: "Bad request, e.g. malformed query parameter"
          body:
            text/plain:
              example: "query parameter is empty"
        500:
          description: "Internal server error, e.g. due to misconfiguration"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
    /{instanceId}:
      type:
        collection-item:
          exampleItem: !include examples/instance_get.json
          schema: instance
      get:
      put:
        is: [validate]
      patch:
        description: Partial update of instance with given ID
        body:
          application/json:
            type: patchRequest
            example: !include examples/patch-request.json
        responses:
          204:
            description: "Instance successfully updated"
          404:
            description: "Instance with a given ID not found"
            body:
              text/plain:
                example: Not found
          400:
            description: "Bad request, e.g. malformed request body or query parameter."
            body:
              text/plain:
                example: "unable to update instance - malformed JSON"
          409:
            description: "Optimistic locking version conflict"
            body:
              text/plain:
                example: "version conflict"
          500:
            description: "Internal server error, e.g. due to misconfiguration"
            body:
              text/plain:
                example: "internal server error, contact administrator"
      /mark-deleted:
        delete:
          description: Toggle the suppression state of an instance record, affecting either instance and associated MARC record if present.
          responses:
            204:
              description: Instance marked as deleted.
            404:
              description: "Instance not found"
              body:
                text/plain:
                  example: "Instance with such id not found"
            422:
              description: "Validation error"
              body:
                application/json:
                  type: errors
            500:
              description: "Internal server error"
              body:
                text/plain:
                  example: "Internal server error"