circulation.raml

#%RAML 1.0
title: Circulation
version: v14.2
protocols: [ HTTP, HTTPS ]
baseUri: http://localhost:9130

documentation:
  - title: Circulation Business Logic API
    content: <b>API for loans and requests</b>

types:
  loan: !include loan.json
  loans: !include loans.json
  request: !include request.json
  requests: !include requests.json
  check-in-by-barcode-response: !include check-in-by-barcode-response.json
  error: !include extended-error.json
  errors: !include extended-errors.json

traits:
  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-get: !include raml-util/rtypes/collection-get.raml
  collection-item: !include raml-util/rtypes/item-collection.raml

/circulation:
  /check-out-by-barcode:
    displayName: Check out using barcode for item and loanee
    post:
      description: Creates a loan by checking out an item to a loanee
      is: [
        validate
      ]
      body:
        application/json:
          type: !include check-out-by-barcode-request.json
          example: !include examples/check-out-by-barcode-request.json
      responses:
        201:
          body:
            application/json:
              type: loan
              example: !include examples/loan.json
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"

  /renew-by-barcode:
    displayName: Renew an existing loan using barcode for item and loanee
    post:
      description: Updates the due date of an existing loan
      is: [
        validate
      ]
      body:
        application/json:
          type: !include renew-by-barcode-request.json
          example: !include examples/renew-by-barcode-request.json
      responses:
        200:
          body:
            application/json:
              type: loan
              example: !include examples/loan.json
        201:
          body:
            application/json:
              type: loan
              example: !include examples/loan.json
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /renew-by-id:
    displayName: Renew an existing loan using IDs of the item and loanee
    post:
      description: Updates the due date of an existing loan
      is: [
        validate
      ]
      body:
        application/json:
          type: !include renew-by-id-request.json
          example: !include examples/renew-by-id-request.json
      responses:
        200:
          body:
            application/json:
              type: loan
              example: !include examples/loan.json
        201:
          body:
            application/json:
              type: loan
              example: !include examples/loan.json
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /check-in-by-barcode:
    displayName: Checkin an existing loan using barcode for item and loanee
    post:
      description: Updates the status of an existing loan
      is: [
        validate
      ]
      body:
        application/json:
          type: !include check-in-by-barcode-request.json
          example: !include examples/check-in-by-barcode-request.json
      responses:
        200:
          body:
            application/json:
              type: check-in-by-barcode-response
              example: !include examples/check-in-by-barcode-response.json
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /loans:
    displayName: Loans
    type:
      collection:
        exampleCollection: !include examples/loans.json
        exampleItem: !include examples/loan.json
        schemaCollection: loans
        schemaItem: loan
    get:
      is: [
        pageable,
        searchable: {description: "by title (using CQL)",
                        example: "userId=\"cf23adf0-61ba-4887-bf82-956c4aae2260\""}
      ]
      responses:
        501:
          description: "Not implemented yet"
    post:
    delete:
      responses:
        204:
          description: "All loans deleted"
        500:
          description: "Internal server error, e.g. due to misconfiguration"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
    /{loanId}:
      type:
        collection-item:
          exampleItem: !include examples/loan.json
          schema: loan
      get:
        responses:
          501:
            description: "Not implemented yet"
      put:
        responses:
          501:
            description: "Not implemented yet"
      delete:
        responses:
          501:
            description: "Not implemented yet"
  /requests:
    displayName: Requests
    type:
      collection:
        exampleCollection: !include examples/requests.json
        exampleItem: !include examples/request.json
        schemaCollection: requests
        schemaItem: request
    get:
      is: [pageable,
        searchable: {description: "by using CQL",
                        example: "requesterId=\"cf23adf0-61ba-4887-bf82-956c4aae2260\""}
        ]
      responses:
        501:
          description: "Not implemented yet"
    post:
      responses:
        501:
          description: "Not implemented yet"
    delete:
      responses:
        204:
          description: "All requests deleted"
        500:
          description: "Internal server error, e.g. due to misconfiguration"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
        501:
          description: "Not implemented yet"
    /{requestId}:
      type:
        collection-item:
          exampleItem: !include examples/request.json
          schema: request
      get:
        responses:
          501:
            description: "Not implemented yet"
      put:
        responses:
          501:
            description: "Not implemented yet"
      delete:
        responses:
          501:
            description: "Not implemented yet"
    /queue:
      /instance:
        /{instanceId}:
          type:
            collection-get:
              exampleCollection: !include examples/request-queue.json
              schemaCollection: requests
          get:
          /reorder:
            post:
              description: Reorder requests in the instance queue
              body:
                application/json:
                  type: !include schema/reorder-queue.json
                  example: !include examples/reorder-queue.json
              responses:
                200:
                  description: "Queue has been reordered successfully"
                  body:
                    application/json:
                      type: requests
                      example: !include examples/requests.json
                422:
                  description: "Validation errors."
                  body:
                    text/plain:
                      example: "Page requests can not be displaced from position 1."
                404:
                  description: "Queue for item not found."
                500:
                  description: "Internal server error."
                  body:
                    text/plain:
                      example: "Internal server error."
      /item:
        /{itemId}:
          type:
            collection-get:
              exampleCollection: !include examples/request-queue.json
              schemaCollection: requests
          get:
          /reorder:
            post:
              description: Reorder requests in the item queue
              body:
                application/json:
                  type: !include schema/reorder-queue.json
                  example: !include examples/reorder-queue.json
              responses:
                200:
                  description: "Queue has been reordered successfully"
                  body:
                    application/json:
                      type: requests
                      example: !include examples/requests.json
                422:
                  description: "Validation errors."
                  body:
                    text/plain:
                      example: "Page requests can not be displaced from position 1."
                404:
                  description: "Queue for item not found."
                500:
                  description: "Internal server error."
                  body:
                    text/plain:
                      example: "Internal server error."
    /instances:
      displayName: Instance level requests
      post:
        description: Creates a request for any item from the given instance ID
        is: [
          validate
        ]
        body:
          application/json:
            type: !include request-by-instance-id.json
            example: !include examples/request-by-instance-id.json
        responses:
          201:
            body:
              application/json:
                type: request
                example: !include examples/request.json
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
    /allowed-service-points:
      displayName: Allowed pickup service points by request type
      get:
        description: Get allowed pickup service points grouped by request type
        queryString:
          minProperties: 2
          maxProperties: 2
          properties:
            operation:
              description: "Operation (create, replace or move)"
              type: string
              enum: [create, replace, move]
              required: false
            requestId:
              description: "Request ID"
              pattern: "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
              required: false
            requesterId:
              description: "Requester ID"
              pattern: "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
              required: false
            itemId:
              description: "Item ID"
              pattern: "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
              required: false
            instanceId:
              description: "Instance ID"
              pattern: "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
              required: false
            useStubItem:
              description: "When true, allows to apply circulation rules based on patron group only"
              type: boolean
              required: false
            ecsRequestRouting:
              description: "When true, returns only service points with ecsRequestRouting"
              type: boolean
              required: false
        responses:
          200:
            description: "List of allowed service points was retrieved successfully"
            body:
              application/json:
                type: !include allowed-service-points-response.json
                example: !include examples/allowed-service-points-response.json
          400:
            description: "Invalid request"
            body:
              text/plain:
                example: "Request query parameters must contain 'requester'"
          422:
            description: "Validation failure"
            body:
              text/plain:
                example: "Validation failed"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"