inventory.raml

#%RAML 1.0
title: Inventory API
version: v13.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
  holdings: !include holdings-record.json
  instance: !include instance.json
  instances: !include instances.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"
    /{itemId}:
      type:
        collection-item:
          exampleItem: !include examples/item_get.json
          schema: item
      get:
      /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: [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]\""}
          ]
  /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]