Circulation (v5.3)

http://localhost:9130

Table of contents

Circulation Business Logic API

API for loans and requests

/circulation

POST /circulation/check-out-by-barcode

Creates a loan by checking out an item to a loanee

POST /circulation/check-out-by-barcode
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Request to check out an item to a loanee using barcodes",
  "properties": {
    "itemBarcode": {
      "description": "Barcode of the item to be lent to the patron",
      "type": "string"
    },
    "userBarcode": {
      "description": "Barcode of the user (representing the patron) the item is to be lent to",
      "type": "string"
    },
    "proxyUserBarcode": {
      "description": "Barcode of the user representing a proxy for the patron",
      "type": "string"
    },
    "loanDate": {
      "description": "When the loan is to begin, defaults to current date and time",
      "type": "string",
      "format": "date-time"
    },
    "servicePointId": {
      "description": "Service point where the item has been checked out",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    }
  },
  "required": [
    "itemBarcode",
    "userBarcode",
    "servicePointId"
  ]
}

Example:

{
  "userBarcode": "466983136459401",
  "proxyUserBarcode": "693750137582350",
  "itemBarcode": "2887532577331",
  "servicePointId": "3260a6f0-0b53-4d9c-ad74-2dba3830d69f"
}

Response 201

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "title": "Loan",
  "description": "Links the item with the patron and applies certain conditions based on policies",
  "properties": {
    "id": {
      "description": "Unique ID (generated UUID) of the loan",
      "type": "string"
    },
    "userId": {
      "description": "ID of the patron the item was lent to. Required for open loans, not required for closed loans (for anonymization).",
      "type": "string"
    },
    "proxyUserId": {
      "description": "ID of the user representing a proxy for the patron",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "itemId": {
      "description": "ID of the item lent to the patron",
      "type": "string"
    },
    "loanPolicyId": {
      "description": "ID of last policy used in relation to this loan",
      "type": "string"
    },
    "item": {
      "description": "Additional information about the item",
      "type": "object",
      "properties": {
        "id": {
          "description": "ID of the item",
          "type": "string"
        },
        "title": {
          "description": "The title of the item lent to the patron",
          "type": "string"
        },
        "callNumber" : {
          "description" : "The call number from the holdings record",
          "type": "string"
        },
        "materialType": {
          "description": "The material type from the item record",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "contributors": {
            "description": "Contributors from the instance record",
            "type": "array",
            "items" : {
              "type": "object",
              "properties" : {
                 "name" : {
                    "type" : "string"
                  }
              },
              "additionalProperties": false
          }
        },
        "holdingsRecordId": {
          "description": "The ID of the holdings for the item",
          "type": "string"
        },
        "instanceId": {
          "description": "The ID of the instance for the item",
          "type": "string"
        },
        "barcode": {
          "description": "The barcode of the item",
          "type": "string"
        },
        "location": {
          "description": "The effective location of the item",
          "type": "object",
          "properties": {
            "name": {
              "description": "The name of the location",
              "type": "string"
            }
          }
        },
        "status": {
          "description": "Overall status of the item",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        },
        "inTransitDestinationServicePointId": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "inTransitDestinationServicePoint": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        }
      }
    },
    "status": {
      "description": "Overall status of the loan",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the status (currently can be any value, values commonly used are Open and Closed)",
          "type": "string"
        }
      }
    },
    "loanDate": {
      "description": "Date and time when the loan began",
      "type": "string",
      "format": "date-time"
    },
    "dueDate": {
      "description": "Date and time when the item is due to be returned",
      "type": "string",
      "format": "date-time"
    },
    "returnDate": {
      "description": "Date and time when the item was returned",
      "type": "string",
      "format": "date-time"
    },
    "systemReturnDate": {
      "description": "Date and time when return was processed",
      "type": "string",
      "format": "date-time"
    },
    "action": {
      "description": "Last action performed on a loan (currently can be any value, values commonly used are checkedout and checkedin)",
      "type": "string"
    },
    "renewalCount": {
      "description": "Count of how many times a loan has been renewed (incremented by the client)",
      "type": "integer"
    },
    "checkoutServicePointId": {
      "description": "ID of the Service Point where the last checkout occured",
      "type": "string"
    },
    "checkinServicePointId": {
      "description": "ID of the Service Point where the last checkin occured",
      "type": "string"
    },
    "checkoutServicePoint": {
      "description": "The Service Point where the last checkout occurred",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique name of the service point"
        },
        "code": {
          "description": "The short code for the service point",
          "type": "string"
        },
        "discoveryDisplayName":{
          "description": "The human readable name",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "The time to shelving",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this a pickup location",
          "type": "boolean"
        }
      }
    },
    "checkinServicePoint": {
      "description": "The Service Point where the last checkout occurred",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique name of the service point"
        },
        "code": {
          "description": "The short code for the service point",
          "type": "string"
        },
        "discoveryDisplayName":{
          "description": "The human readable name",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "The time to shelving",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this a pickup location",
          "type": "boolean"
        }
      }
    },
    "metadata": {
      "description": "Metadata about creation and changes to loan, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "required": [
    "itemId",
    "loanDate",
    "action"
  ]
}

Example:

{
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "userId": "df7f4993-8c14-4a0f-ab63-93975ab01c76",
  "proxyUserId": "346ad017-dac1-417d-9ed8-0ac7eeb886aa",
  "itemId": "cb20f34f-b773-462f-a091-b233cc96b9e6",
  "item": {
    "title": "The Long Way to a Small, Angry Planet",
    "barcode": "036000291452",
    "status": {
      "name": "Checked Out"
    },
    "location": {
      "name": "Main Library"
    },
    "materialType": {
      "name": "Book"
    },
    "contributors": [
      {
        "name": "Steve Jones"
      }
    ]
  },
  "loanDate": "2017-03-01T23:11:00.000Z",
  "dueDate": "2017-04-01T23:11:00.000Z",
  "checkoutServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "checkinServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "status": {
    "name": "Open"
  },
  "action": "checkedout",
  "renewalCount": 0
}

Response 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "error.schema"
      }
    },
    "total_records": {
      "type": "integer"
    }
  }
}

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /circulation/renew-by-barcode

Updates the due date of an existing loan

POST /circulation/renew-by-barcode
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Request to renew an existing loan, found by barcodes of item and loanee",
  "properties": {
    "itemBarcode": {
      "description": "Barcode of the item to be renewed",
      "type": "string"
    },
    "userBarcode": {
      "description": "Barcode of the user (representing the patron) the item has been loaned to",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "itemBarcode",
    "userBarcode"
  ]
}

Example:

{
  "userBarcode": "466983136459401",
  "itemBarcode": "2887532577331"
}

Response 200

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "title": "Loan",
  "description": "Links the item with the patron and applies certain conditions based on policies",
  "properties": {
    "id": {
      "description": "Unique ID (generated UUID) of the loan",
      "type": "string"
    },
    "userId": {
      "description": "ID of the patron the item was lent to. Required for open loans, not required for closed loans (for anonymization).",
      "type": "string"
    },
    "proxyUserId": {
      "description": "ID of the user representing a proxy for the patron",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "itemId": {
      "description": "ID of the item lent to the patron",
      "type": "string"
    },
    "loanPolicyId": {
      "description": "ID of last policy used in relation to this loan",
      "type": "string"
    },
    "item": {
      "description": "Additional information about the item",
      "type": "object",
      "properties": {
        "id": {
          "description": "ID of the item",
          "type": "string"
        },
        "title": {
          "description": "The title of the item lent to the patron",
          "type": "string"
        },
        "callNumber" : {
          "description" : "The call number from the holdings record",
          "type": "string"
        },
        "materialType": {
          "description": "The material type from the item record",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "contributors": {
            "description": "Contributors from the instance record",
            "type": "array",
            "items" : {
              "type": "object",
              "properties" : {
                 "name" : {
                    "type" : "string"
                  }
              },
              "additionalProperties": false
          }
        },
        "holdingsRecordId": {
          "description": "The ID of the holdings for the item",
          "type": "string"
        },
        "instanceId": {
          "description": "The ID of the instance for the item",
          "type": "string"
        },
        "barcode": {
          "description": "The barcode of the item",
          "type": "string"
        },
        "location": {
          "description": "The effective location of the item",
          "type": "object",
          "properties": {
            "name": {
              "description": "The name of the location",
              "type": "string"
            }
          }
        },
        "status": {
          "description": "Overall status of the item",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        },
        "inTransitDestinationServicePointId": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "inTransitDestinationServicePoint": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        }
      }
    },
    "status": {
      "description": "Overall status of the loan",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the status (currently can be any value, values commonly used are Open and Closed)",
          "type": "string"
        }
      }
    },
    "loanDate": {
      "description": "Date and time when the loan began",
      "type": "string",
      "format": "date-time"
    },
    "dueDate": {
      "description": "Date and time when the item is due to be returned",
      "type": "string",
      "format": "date-time"
    },
    "returnDate": {
      "description": "Date and time when the item was returned",
      "type": "string",
      "format": "date-time"
    },
    "systemReturnDate": {
      "description": "Date and time when return was processed",
      "type": "string",
      "format": "date-time"
    },
    "action": {
      "description": "Last action performed on a loan (currently can be any value, values commonly used are checkedout and checkedin)",
      "type": "string"
    },
    "renewalCount": {
      "description": "Count of how many times a loan has been renewed (incremented by the client)",
      "type": "integer"
    },
    "checkoutServicePointId": {
      "description": "ID of the Service Point where the last checkout occured",
      "type": "string"
    },
    "checkinServicePointId": {
      "description": "ID of the Service Point where the last checkin occured",
      "type": "string"
    },
    "checkoutServicePoint": {
      "description": "The Service Point where the last checkout occurred",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique name of the service point"
        },
        "code": {
          "description": "The short code for the service point",
          "type": "string"
        },
        "discoveryDisplayName":{
          "description": "The human readable name",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "The time to shelving",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this a pickup location",
          "type": "boolean"
        }
      }
    },
    "checkinServicePoint": {
      "description": "The Service Point where the last checkout occurred",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique name of the service point"
        },
        "code": {
          "description": "The short code for the service point",
          "type": "string"
        },
        "discoveryDisplayName":{
          "description": "The human readable name",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "The time to shelving",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this a pickup location",
          "type": "boolean"
        }
      }
    },
    "metadata": {
      "description": "Metadata about creation and changes to loan, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "required": [
    "itemId",
    "loanDate",
    "action"
  ]
}

Example:

{
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "userId": "df7f4993-8c14-4a0f-ab63-93975ab01c76",
  "proxyUserId": "346ad017-dac1-417d-9ed8-0ac7eeb886aa",
  "itemId": "cb20f34f-b773-462f-a091-b233cc96b9e6",
  "item": {
    "title": "The Long Way to a Small, Angry Planet",
    "barcode": "036000291452",
    "status": {
      "name": "Checked Out"
    },
    "location": {
      "name": "Main Library"
    },
    "materialType": {
      "name": "Book"
    },
    "contributors": [
      {
        "name": "Steve Jones"
      }
    ]
  },
  "loanDate": "2017-03-01T23:11:00.000Z",
  "dueDate": "2017-04-01T23:11:00.000Z",
  "checkoutServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "checkinServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "status": {
    "name": "Open"
  },
  "action": "checkedout",
  "renewalCount": 0
}

Response 201

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "title": "Loan",
  "description": "Links the item with the patron and applies certain conditions based on policies",
  "properties": {
    "id": {
      "description": "Unique ID (generated UUID) of the loan",
      "type": "string"
    },
    "userId": {
      "description": "ID of the patron the item was lent to. Required for open loans, not required for closed loans (for anonymization).",
      "type": "string"
    },
    "proxyUserId": {
      "description": "ID of the user representing a proxy for the patron",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "itemId": {
      "description": "ID of the item lent to the patron",
      "type": "string"
    },
    "loanPolicyId": {
      "description": "ID of last policy used in relation to this loan",
      "type": "string"
    },
    "item": {
      "description": "Additional information about the item",
      "type": "object",
      "properties": {
        "id": {
          "description": "ID of the item",
          "type": "string"
        },
        "title": {
          "description": "The title of the item lent to the patron",
          "type": "string"
        },
        "callNumber" : {
          "description" : "The call number from the holdings record",
          "type": "string"
        },
        "materialType": {
          "description": "The material type from the item record",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "contributors": {
            "description": "Contributors from the instance record",
            "type": "array",
            "items" : {
              "type": "object",
              "properties" : {
                 "name" : {
                    "type" : "string"
                  }
              },
              "additionalProperties": false
          }
        },
        "holdingsRecordId": {
          "description": "The ID of the holdings for the item",
          "type": "string"
        },
        "instanceId": {
          "description": "The ID of the instance for the item",
          "type": "string"
        },
        "barcode": {
          "description": "The barcode of the item",
          "type": "string"
        },
        "location": {
          "description": "The effective location of the item",
          "type": "object",
          "properties": {
            "name": {
              "description": "The name of the location",
              "type": "string"
            }
          }
        },
        "status": {
          "description": "Overall status of the item",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        },
        "inTransitDestinationServicePointId": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "inTransitDestinationServicePoint": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        }
      }
    },
    "status": {
      "description": "Overall status of the loan",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the status (currently can be any value, values commonly used are Open and Closed)",
          "type": "string"
        }
      }
    },
    "loanDate": {
      "description": "Date and time when the loan began",
      "type": "string",
      "format": "date-time"
    },
    "dueDate": {
      "description": "Date and time when the item is due to be returned",
      "type": "string",
      "format": "date-time"
    },
    "returnDate": {
      "description": "Date and time when the item was returned",
      "type": "string",
      "format": "date-time"
    },
    "systemReturnDate": {
      "description": "Date and time when return was processed",
      "type": "string",
      "format": "date-time"
    },
    "action": {
      "description": "Last action performed on a loan (currently can be any value, values commonly used are checkedout and checkedin)",
      "type": "string"
    },
    "renewalCount": {
      "description": "Count of how many times a loan has been renewed (incremented by the client)",
      "type": "integer"
    },
    "checkoutServicePointId": {
      "description": "ID of the Service Point where the last checkout occured",
      "type": "string"
    },
    "checkinServicePointId": {
      "description": "ID of the Service Point where the last checkin occured",
      "type": "string"
    },
    "checkoutServicePoint": {
      "description": "The Service Point where the last checkout occurred",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique name of the service point"
        },
        "code": {
          "description": "The short code for the service point",
          "type": "string"
        },
        "discoveryDisplayName":{
          "description": "The human readable name",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "The time to shelving",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this a pickup location",
          "type": "boolean"
        }
      }
    },
    "checkinServicePoint": {
      "description": "The Service Point where the last checkout occurred",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique name of the service point"
        },
        "code": {
          "description": "The short code for the service point",
          "type": "string"
        },
        "discoveryDisplayName":{
          "description": "The human readable name",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "The time to shelving",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this a pickup location",
          "type": "boolean"
        }
      }
    },
    "metadata": {
      "description": "Metadata about creation and changes to loan, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "required": [
    "itemId",
    "loanDate",
    "action"
  ]
}

Example:

{
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "userId": "df7f4993-8c14-4a0f-ab63-93975ab01c76",
  "proxyUserId": "346ad017-dac1-417d-9ed8-0ac7eeb886aa",
  "itemId": "cb20f34f-b773-462f-a091-b233cc96b9e6",
  "item": {
    "title": "The Long Way to a Small, Angry Planet",
    "barcode": "036000291452",
    "status": {
      "name": "Checked Out"
    },
    "location": {
      "name": "Main Library"
    },
    "materialType": {
      "name": "Book"
    },
    "contributors": [
      {
        "name": "Steve Jones"
      }
    ]
  },
  "loanDate": "2017-03-01T23:11:00.000Z",
  "dueDate": "2017-04-01T23:11:00.000Z",
  "checkoutServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "checkinServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "status": {
    "name": "Open"
  },
  "action": "checkedout",
  "renewalCount": 0
}

Response 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "error.schema"
      }
    },
    "total_records": {
      "type": "integer"
    }
  }
}

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /circulation/renew-by-id

Updates the due date of an existing loan

POST /circulation/renew-by-id
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Request to renew an existing loan, found by the IDs of item and loanee",
  "properties": {
    "itemId": {
      "description": "ID of the item to be renewed",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "userId": {
      "description": "ID of the user (representing the patron) the item has been loaned to",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    }
  },
  "additionalProperties": false,
  "required": [
    "itemId",
    "userId"
  ]
}

Example:

{
  "userId": "6c4706ad-3a76-4251-b030-4609027a7918",
  "itemId": "51763f82-c8e6-4486-9fdc-1c1664352550"
}

Response 200

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "title": "Loan",
  "description": "Links the item with the patron and applies certain conditions based on policies",
  "properties": {
    "id": {
      "description": "Unique ID (generated UUID) of the loan",
      "type": "string"
    },
    "userId": {
      "description": "ID of the patron the item was lent to. Required for open loans, not required for closed loans (for anonymization).",
      "type": "string"
    },
    "proxyUserId": {
      "description": "ID of the user representing a proxy for the patron",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "itemId": {
      "description": "ID of the item lent to the patron",
      "type": "string"
    },
    "loanPolicyId": {
      "description": "ID of last policy used in relation to this loan",
      "type": "string"
    },
    "item": {
      "description": "Additional information about the item",
      "type": "object",
      "properties": {
        "id": {
          "description": "ID of the item",
          "type": "string"
        },
        "title": {
          "description": "The title of the item lent to the patron",
          "type": "string"
        },
        "callNumber" : {
          "description" : "The call number from the holdings record",
          "type": "string"
        },
        "materialType": {
          "description": "The material type from the item record",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "contributors": {
            "description": "Contributors from the instance record",
            "type": "array",
            "items" : {
              "type": "object",
              "properties" : {
                 "name" : {
                    "type" : "string"
                  }
              },
              "additionalProperties": false
          }
        },
        "holdingsRecordId": {
          "description": "The ID of the holdings for the item",
          "type": "string"
        },
        "instanceId": {
          "description": "The ID of the instance for the item",
          "type": "string"
        },
        "barcode": {
          "description": "The barcode of the item",
          "type": "string"
        },
        "location": {
          "description": "The effective location of the item",
          "type": "object",
          "properties": {
            "name": {
              "description": "The name of the location",
              "type": "string"
            }
          }
        },
        "status": {
          "description": "Overall status of the item",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        },
        "inTransitDestinationServicePointId": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "inTransitDestinationServicePoint": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        }
      }
    },
    "status": {
      "description": "Overall status of the loan",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the status (currently can be any value, values commonly used are Open and Closed)",
          "type": "string"
        }
      }
    },
    "loanDate": {
      "description": "Date and time when the loan began",
      "type": "string",
      "format": "date-time"
    },
    "dueDate": {
      "description": "Date and time when the item is due to be returned",
      "type": "string",
      "format": "date-time"
    },
    "returnDate": {
      "description": "Date and time when the item was returned",
      "type": "string",
      "format": "date-time"
    },
    "systemReturnDate": {
      "description": "Date and time when return was processed",
      "type": "string",
      "format": "date-time"
    },
    "action": {
      "description": "Last action performed on a loan (currently can be any value, values commonly used are checkedout and checkedin)",
      "type": "string"
    },
    "renewalCount": {
      "description": "Count of how many times a loan has been renewed (incremented by the client)",
      "type": "integer"
    },
    "checkoutServicePointId": {
      "description": "ID of the Service Point where the last checkout occured",
      "type": "string"
    },
    "checkinServicePointId": {
      "description": "ID of the Service Point where the last checkin occured",
      "type": "string"
    },
    "checkoutServicePoint": {
      "description": "The Service Point where the last checkout occurred",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique name of the service point"
        },
        "code": {
          "description": "The short code for the service point",
          "type": "string"
        },
        "discoveryDisplayName":{
          "description": "The human readable name",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "The time to shelving",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this a pickup location",
          "type": "boolean"
        }
      }
    },
    "checkinServicePoint": {
      "description": "The Service Point where the last checkout occurred",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique name of the service point"
        },
        "code": {
          "description": "The short code for the service point",
          "type": "string"
        },
        "discoveryDisplayName":{
          "description": "The human readable name",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "The time to shelving",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this a pickup location",
          "type": "boolean"
        }
      }
    },
    "metadata": {
      "description": "Metadata about creation and changes to loan, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "required": [
    "itemId",
    "loanDate",
    "action"
  ]
}

Example:

{
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "userId": "df7f4993-8c14-4a0f-ab63-93975ab01c76",
  "proxyUserId": "346ad017-dac1-417d-9ed8-0ac7eeb886aa",
  "itemId": "cb20f34f-b773-462f-a091-b233cc96b9e6",
  "item": {
    "title": "The Long Way to a Small, Angry Planet",
    "barcode": "036000291452",
    "status": {
      "name": "Checked Out"
    },
    "location": {
      "name": "Main Library"
    },
    "materialType": {
      "name": "Book"
    },
    "contributors": [
      {
        "name": "Steve Jones"
      }
    ]
  },
  "loanDate": "2017-03-01T23:11:00.000Z",
  "dueDate": "2017-04-01T23:11:00.000Z",
  "checkoutServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "checkinServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "status": {
    "name": "Open"
  },
  "action": "checkedout",
  "renewalCount": 0
}

Response 201

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "title": "Loan",
  "description": "Links the item with the patron and applies certain conditions based on policies",
  "properties": {
    "id": {
      "description": "Unique ID (generated UUID) of the loan",
      "type": "string"
    },
    "userId": {
      "description": "ID of the patron the item was lent to. Required for open loans, not required for closed loans (for anonymization).",
      "type": "string"
    },
    "proxyUserId": {
      "description": "ID of the user representing a proxy for the patron",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "itemId": {
      "description": "ID of the item lent to the patron",
      "type": "string"
    },
    "loanPolicyId": {
      "description": "ID of last policy used in relation to this loan",
      "type": "string"
    },
    "item": {
      "description": "Additional information about the item",
      "type": "object",
      "properties": {
        "id": {
          "description": "ID of the item",
          "type": "string"
        },
        "title": {
          "description": "The title of the item lent to the patron",
          "type": "string"
        },
        "callNumber" : {
          "description" : "The call number from the holdings record",
          "type": "string"
        },
        "materialType": {
          "description": "The material type from the item record",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "contributors": {
            "description": "Contributors from the instance record",
            "type": "array",
            "items" : {
              "type": "object",
              "properties" : {
                 "name" : {
                    "type" : "string"
                  }
              },
              "additionalProperties": false
          }
        },
        "holdingsRecordId": {
          "description": "The ID of the holdings for the item",
          "type": "string"
        },
        "instanceId": {
          "description": "The ID of the instance for the item",
          "type": "string"
        },
        "barcode": {
          "description": "The barcode of the item",
          "type": "string"
        },
        "location": {
          "description": "The effective location of the item",
          "type": "object",
          "properties": {
            "name": {
              "description": "The name of the location",
              "type": "string"
            }
          }
        },
        "status": {
          "description": "Overall status of the item",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        },
        "inTransitDestinationServicePointId": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "inTransitDestinationServicePoint": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        }
      }
    },
    "status": {
      "description": "Overall status of the loan",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the status (currently can be any value, values commonly used are Open and Closed)",
          "type": "string"
        }
      }
    },
    "loanDate": {
      "description": "Date and time when the loan began",
      "type": "string",
      "format": "date-time"
    },
    "dueDate": {
      "description": "Date and time when the item is due to be returned",
      "type": "string",
      "format": "date-time"
    },
    "returnDate": {
      "description": "Date and time when the item was returned",
      "type": "string",
      "format": "date-time"
    },
    "systemReturnDate": {
      "description": "Date and time when return was processed",
      "type": "string",
      "format": "date-time"
    },
    "action": {
      "description": "Last action performed on a loan (currently can be any value, values commonly used are checkedout and checkedin)",
      "type": "string"
    },
    "renewalCount": {
      "description": "Count of how many times a loan has been renewed (incremented by the client)",
      "type": "integer"
    },
    "checkoutServicePointId": {
      "description": "ID of the Service Point where the last checkout occured",
      "type": "string"
    },
    "checkinServicePointId": {
      "description": "ID of the Service Point where the last checkin occured",
      "type": "string"
    },
    "checkoutServicePoint": {
      "description": "The Service Point where the last checkout occurred",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique name of the service point"
        },
        "code": {
          "description": "The short code for the service point",
          "type": "string"
        },
        "discoveryDisplayName":{
          "description": "The human readable name",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "The time to shelving",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this a pickup location",
          "type": "boolean"
        }
      }
    },
    "checkinServicePoint": {
      "description": "The Service Point where the last checkout occurred",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique name of the service point"
        },
        "code": {
          "description": "The short code for the service point",
          "type": "string"
        },
        "discoveryDisplayName":{
          "description": "The human readable name",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "The time to shelving",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this a pickup location",
          "type": "boolean"
        }
      }
    },
    "metadata": {
      "description": "Metadata about creation and changes to loan, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "required": [
    "itemId",
    "loanDate",
    "action"
  ]
}

Example:

{
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "userId": "df7f4993-8c14-4a0f-ab63-93975ab01c76",
  "proxyUserId": "346ad017-dac1-417d-9ed8-0ac7eeb886aa",
  "itemId": "cb20f34f-b773-462f-a091-b233cc96b9e6",
  "item": {
    "title": "The Long Way to a Small, Angry Planet",
    "barcode": "036000291452",
    "status": {
      "name": "Checked Out"
    },
    "location": {
      "name": "Main Library"
    },
    "materialType": {
      "name": "Book"
    },
    "contributors": [
      {
        "name": "Steve Jones"
      }
    ]
  },
  "loanDate": "2017-03-01T23:11:00.000Z",
  "dueDate": "2017-04-01T23:11:00.000Z",
  "checkoutServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "checkinServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "status": {
    "name": "Open"
  },
  "action": "checkedout",
  "renewalCount": 0
}

Response 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "error.schema"
      }
    },
    "total_records": {
      "type": "integer"
    }
  }
}

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /circulation/check-in-by-barcode

Updates the status of an existing loan

POST /circulation/check-in-by-barcode
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Request to check in an item at a service point (including when a loan is returned)",
  "properties": {
    "itemBarcode": {
      "description": "Barcode of the item to be checked in",
      "type": "string"
    },
    "servicePointId": {
      "description": "Service point where the item is being processed",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "checkInDate": {
      "description": "When the item was checked in",
      "type": "string",
      "format": "date-time"
    }
  },
  "additionalProperties": false,
  "required": [
    "itemBarcode",
    "checkInDate",
    "servicePointId"
  ]
}

Example:

{
  "itemBarcode": "2887532577331",
  "servicePointId": "8359f2bc-b83e-48e1-8a5b-ca1a74e840de",
  "checkInDate": "2018-03-05T14:23:41.000Z"
}

Response 200

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Success response for checking in an item at a service point",
  "properties": {
    "loan": {
      "description": "Loan affected by the check in (may be none, if a receiving check in)",
      "$ref": "loan.json"
    },
    "item": {
      "description": "Additional information about the item",
      "type": "object",
      "properties": {
        "id": {
          "description": "ID of the item",
          "type": "string"
        },
        "title": {
          "description": "The title of the item lent to the patron",
          "type": "string"
        },
        "callNumber" : {
          "description" : "The call number from the holdings record",
          "type": "string"
        },
        "materialType": {
          "description": "The material type from the item record",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "contributors": {
          "description": "Contributors from the instance record",
          "type": "array",
          "items" : {
            "type": "object",
            "properties" : {
              "name" : {
                "type" : "string"
              }
            },
            "additionalProperties": false
          }
        },
        "holdingsRecordId": {
          "description": "The ID of the holdings for the item",
          "type": "string"
        },
        "instanceId": {
          "description": "The ID of the instance for the item",
          "type": "string"
        },
        "barcode": {
          "description": "The barcode of the item",
          "type": "string"
        },
        "location": {
          "description": "The effective location of the item",
          "type": "object",
          "properties": {
            "name": {
              "description": "The name of the location",
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "status": {
          "description": "Overall status of the item",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "inTransitDestinationServicePointId": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "inTransitDestinationServicePoint": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Example:

{
  "loan": {
    "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
    "userId": "df7f4993-8c14-4a0f-ab63-93975ab01c76",
    "proxyUserId": "346ad017-dac1-417d-9ed8-0ac7eeb886aa",
    "itemId": "cb20f34f-b773-462f-a091-b233cc96b9e6",
    "item": {
      "title": "The Long Way to a Small, Angry Planet",
      "barcode": "036000291452",
      "status": {
        "name": "Checked Out"
      },
      "location": {
        "name": "Main Library"
      },
      "materialType": {
        "name": "Book"
      },
      "contributors": [
        {
          "name": "Steve Jones"
        }
      ]
    },
    "loanDate": "2017-03-01T23:11:00.000Z",
    "dueDate": "2017-04-01T23:11:00.000Z",
    "checkoutServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
    "checkinServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
    "status": {
      "name": "Open"
    },
    "action": "checkedout",
    "renewalCount": 0
  }
}

Response 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "error.schema"
      }
    },
    "total_records": {
      "type": "integer"
    }
  }
}

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

GET /circulation/loans

Retrieve a list of loan items.

GET /circulation/loans
Query Parameters
  • offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)

    Skip over a number of elements by specifying an offset value for the query

    Example:

    0
  • limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)

    Limit the number of elements returned in the response

    Example:

    10
  • query: (string)

    A query expressed as a CQL string (see dev.folio.org/reference/glossary#cql) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.

    by title (using CQL)

    Example:

    (username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
    
    userId="cf23adf0-61ba-4887-bf82-956c4aae2260"
    
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns a list of loan items

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "loans": {
      "id": "loans",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "loan.json"
      }
    },
    "totalRecords": {
      "type": "integer"
    }
  },
  "required": [
    "loans",
    "totalRecords"
  ]
}

Example:

{
  "loans": [
    {
      "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
      "userId": "df7f4993-8c14-4a0f-ab63-93975ab01c76",
      "proxyUserId": "346ad017-dac1-417d-9ed8-0ac7eeb886aa",
      "itemId": "cb20f34f-b773-462f-a091-b233cc96b9e6",
      "item": {
        "title": "The Long Way to a Small, Angry Planet",
        "barcode": "036000291452",
        "status": {
          "name": "Checked Out"
        }
      },
      "loanDate": "2017-03-01T22:34:11Z",
      "dueDate": "2017-04-01T22:34:11.000Z",
      "status": {
        "name": "Open"
      },
      "location": {
        "name": "Main Library"
      },
      "action": "checkedout",
      "renewalCount": 1
    },
    {
      "id": "1d09af65-aeaa-499c-80cb-d52847b75a60",
      "userId": "15054e48-03e8-4ed5-810b-7192b86accab",
      "itemId": "94838fa2-288a-45c2-ad19-9102f5645127",
      "item": {
        "title": "Nod",
        "barcode": "565578437802",
        "status": {
          "name": "Available"
        },
        "location": {
          "name": "Annex"
        }
      },
      "loanDate": "2017-01-14T19:14:36Z",
      "returnDate": "2017-01-16T09:15:23Z",
      "status": {
        "name": "Closed"
      },
      "action": "checkedin"
    }
  ],
  "totalRecords": 2
}

Response 400

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

Media type: text/plain

Type: any

Example:

unable to list loans -- malformed parameter 'query', syntax error at column 6

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to list loans -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

Response 501

Not implemented yet

POST /circulation/loans

Create a new loan item.

POST /circulation/loans
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "title": "Loan",
  "description": "Links the item with the patron and applies certain conditions based on policies",
  "properties": {
    "id": {
      "description": "Unique ID (generated UUID) of the loan",
      "type": "string"
    },
    "userId": {
      "description": "ID of the patron the item was lent to. Required for open loans, not required for closed loans (for anonymization).",
      "type": "string"
    },
    "proxyUserId": {
      "description": "ID of the user representing a proxy for the patron",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "itemId": {
      "description": "ID of the item lent to the patron",
      "type": "string"
    },
    "loanPolicyId": {
      "description": "ID of last policy used in relation to this loan",
      "type": "string"
    },
    "item": {
      "description": "Additional information about the item",
      "type": "object",
      "properties": {
        "id": {
          "description": "ID of the item",
          "type": "string"
        },
        "title": {
          "description": "The title of the item lent to the patron",
          "type": "string"
        },
        "callNumber" : {
          "description" : "The call number from the holdings record",
          "type": "string"
        },
        "materialType": {
          "description": "The material type from the item record",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "contributors": {
            "description": "Contributors from the instance record",
            "type": "array",
            "items" : {
              "type": "object",
              "properties" : {
                 "name" : {
                    "type" : "string"
                  }
              },
              "additionalProperties": false
          }
        },
        "holdingsRecordId": {
          "description": "The ID of the holdings for the item",
          "type": "string"
        },
        "instanceId": {
          "description": "The ID of the instance for the item",
          "type": "string"
        },
        "barcode": {
          "description": "The barcode of the item",
          "type": "string"
        },
        "location": {
          "description": "The effective location of the item",
          "type": "object",
          "properties": {
            "name": {
              "description": "The name of the location",
              "type": "string"
            }
          }
        },
        "status": {
          "description": "Overall status of the item",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        },
        "inTransitDestinationServicePointId": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "inTransitDestinationServicePoint": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        }
      }
    },
    "status": {
      "description": "Overall status of the loan",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the status (currently can be any value, values commonly used are Open and Closed)",
          "type": "string"
        }
      }
    },
    "loanDate": {
      "description": "Date and time when the loan began",
      "type": "string",
      "format": "date-time"
    },
    "dueDate": {
      "description": "Date and time when the item is due to be returned",
      "type": "string",
      "format": "date-time"
    },
    "returnDate": {
      "description": "Date and time when the item was returned",
      "type": "string",
      "format": "date-time"
    },
    "systemReturnDate": {
      "description": "Date and time when return was processed",
      "type": "string",
      "format": "date-time"
    },
    "action": {
      "description": "Last action performed on a loan (currently can be any value, values commonly used are checkedout and checkedin)",
      "type": "string"
    },
    "renewalCount": {
      "description": "Count of how many times a loan has been renewed (incremented by the client)",
      "type": "integer"
    },
    "checkoutServicePointId": {
      "description": "ID of the Service Point where the last checkout occured",
      "type": "string"
    },
    "checkinServicePointId": {
      "description": "ID of the Service Point where the last checkin occured",
      "type": "string"
    },
    "checkoutServicePoint": {
      "description": "The Service Point where the last checkout occurred",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique name of the service point"
        },
        "code": {
          "description": "The short code for the service point",
          "type": "string"
        },
        "discoveryDisplayName":{
          "description": "The human readable name",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "The time to shelving",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this a pickup location",
          "type": "boolean"
        }
      }
    },
    "checkinServicePoint": {
      "description": "The Service Point where the last checkout occurred",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique name of the service point"
        },
        "code": {
          "description": "The short code for the service point",
          "type": "string"
        },
        "discoveryDisplayName":{
          "description": "The human readable name",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "The time to shelving",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this a pickup location",
          "type": "boolean"
        }
      }
    },
    "metadata": {
      "description": "Metadata about creation and changes to loan, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "required": [
    "itemId",
    "loanDate",
    "action"
  ]
}

Example:

{
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "userId": "df7f4993-8c14-4a0f-ab63-93975ab01c76",
  "proxyUserId": "346ad017-dac1-417d-9ed8-0ac7eeb886aa",
  "itemId": "cb20f34f-b773-462f-a091-b233cc96b9e6",
  "item": {
    "title": "The Long Way to a Small, Angry Planet",
    "barcode": "036000291452",
    "status": {
      "name": "Checked Out"
    },
    "location": {
      "name": "Main Library"
    },
    "materialType": {
      "name": "Book"
    },
    "contributors": [
      {
        "name": "Steve Jones"
      }
    ]
  },
  "loanDate": "2017-03-01T23:11:00.000Z",
  "dueDate": "2017-04-01T23:11:00.000Z",
  "checkoutServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "checkinServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "status": {
    "name": "Open"
  },
  "action": "checkedout",
  "renewalCount": 0
}

Response 201

Returns a newly created item, with server-controlled fields like 'id' populated

Headers
  • Location: required (string)

    URI to the created loan item

Body

Media type: application/json

Type: any

Example:

{
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "userId": "df7f4993-8c14-4a0f-ab63-93975ab01c76",
  "proxyUserId": "346ad017-dac1-417d-9ed8-0ac7eeb886aa",
  "itemId": "cb20f34f-b773-462f-a091-b233cc96b9e6",
  "item": {
    "title": "The Long Way to a Small, Angry Planet",
    "barcode": "036000291452",
    "status": {
      "name": "Checked Out"
    },
    "location": {
      "name": "Main Library"
    },
    "materialType": {
      "name": "Book"
    },
    "contributors": [
      {
        "name": "Steve Jones"
      }
    ]
  },
  "loanDate": "2017-03-01T23:11:00.000Z",
  "dueDate": "2017-04-01T23:11:00.000Z",
  "checkoutServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "checkinServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "status": {
    "name": "Open"
  },
  "action": "checkedout",
  "renewalCount": 0
}

Response 400

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

Media type: text/plain

Type: any

Example:

"unable to add loan -- malformed JSON at 13:3"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create loans -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

DELETE /circulation/loans

DELETE /circulation/loans
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 204

All loans deleted

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

GET /circulation/loans/{loanId}

Retrieve loan item with given {loanId}

GET /circulation/loans/{loanId}
URI Parameters
  • loanId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns item with a given ID

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "title": "Loan",
  "description": "Links the item with the patron and applies certain conditions based on policies",
  "properties": {
    "id": {
      "description": "Unique ID (generated UUID) of the loan",
      "type": "string"
    },
    "userId": {
      "description": "ID of the patron the item was lent to. Required for open loans, not required for closed loans (for anonymization).",
      "type": "string"
    },
    "proxyUserId": {
      "description": "ID of the user representing a proxy for the patron",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "itemId": {
      "description": "ID of the item lent to the patron",
      "type": "string"
    },
    "loanPolicyId": {
      "description": "ID of last policy used in relation to this loan",
      "type": "string"
    },
    "item": {
      "description": "Additional information about the item",
      "type": "object",
      "properties": {
        "id": {
          "description": "ID of the item",
          "type": "string"
        },
        "title": {
          "description": "The title of the item lent to the patron",
          "type": "string"
        },
        "callNumber" : {
          "description" : "The call number from the holdings record",
          "type": "string"
        },
        "materialType": {
          "description": "The material type from the item record",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "contributors": {
            "description": "Contributors from the instance record",
            "type": "array",
            "items" : {
              "type": "object",
              "properties" : {
                 "name" : {
                    "type" : "string"
                  }
              },
              "additionalProperties": false
          }
        },
        "holdingsRecordId": {
          "description": "The ID of the holdings for the item",
          "type": "string"
        },
        "instanceId": {
          "description": "The ID of the instance for the item",
          "type": "string"
        },
        "barcode": {
          "description": "The barcode of the item",
          "type": "string"
        },
        "location": {
          "description": "The effective location of the item",
          "type": "object",
          "properties": {
            "name": {
              "description": "The name of the location",
              "type": "string"
            }
          }
        },
        "status": {
          "description": "Overall status of the item",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        },
        "inTransitDestinationServicePointId": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "inTransitDestinationServicePoint": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        }
      }
    },
    "status": {
      "description": "Overall status of the loan",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the status (currently can be any value, values commonly used are Open and Closed)",
          "type": "string"
        }
      }
    },
    "loanDate": {
      "description": "Date and time when the loan began",
      "type": "string",
      "format": "date-time"
    },
    "dueDate": {
      "description": "Date and time when the item is due to be returned",
      "type": "string",
      "format": "date-time"
    },
    "returnDate": {
      "description": "Date and time when the item was returned",
      "type": "string",
      "format": "date-time"
    },
    "systemReturnDate": {
      "description": "Date and time when return was processed",
      "type": "string",
      "format": "date-time"
    },
    "action": {
      "description": "Last action performed on a loan (currently can be any value, values commonly used are checkedout and checkedin)",
      "type": "string"
    },
    "renewalCount": {
      "description": "Count of how many times a loan has been renewed (incremented by the client)",
      "type": "integer"
    },
    "checkoutServicePointId": {
      "description": "ID of the Service Point where the last checkout occured",
      "type": "string"
    },
    "checkinServicePointId": {
      "description": "ID of the Service Point where the last checkin occured",
      "type": "string"
    },
    "checkoutServicePoint": {
      "description": "The Service Point where the last checkout occurred",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique name of the service point"
        },
        "code": {
          "description": "The short code for the service point",
          "type": "string"
        },
        "discoveryDisplayName":{
          "description": "The human readable name",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "The time to shelving",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this a pickup location",
          "type": "boolean"
        }
      }
    },
    "checkinServicePoint": {
      "description": "The Service Point where the last checkout occurred",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique name of the service point"
        },
        "code": {
          "description": "The short code for the service point",
          "type": "string"
        },
        "discoveryDisplayName":{
          "description": "The human readable name",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "The time to shelving",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this a pickup location",
          "type": "boolean"
        }
      }
    },
    "metadata": {
      "description": "Metadata about creation and changes to loan, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "required": [
    "itemId",
    "loanDate",
    "action"
  ]
}

Example:

{
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "userId": "df7f4993-8c14-4a0f-ab63-93975ab01c76",
  "proxyUserId": "346ad017-dac1-417d-9ed8-0ac7eeb886aa",
  "itemId": "cb20f34f-b773-462f-a091-b233cc96b9e6",
  "item": {
    "title": "The Long Way to a Small, Angry Planet",
    "barcode": "036000291452",
    "status": {
      "name": "Checked Out"
    },
    "location": {
      "name": "Main Library"
    },
    "materialType": {
      "name": "Book"
    },
    "contributors": [
      {
        "name": "Steve Jones"
      }
    ]
  },
  "loanDate": "2017-03-01T23:11:00.000Z",
  "dueDate": "2017-04-01T23:11:00.000Z",
  "checkoutServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "checkinServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "status": {
    "name": "Open"
  },
  "action": "checkedout",
  "renewalCount": 0
}

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"loan not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

Response 501

Not implemented yet

PUT /circulation/loans/{loanId}

Update loan item with given {loanId}

PUT /circulation/loans/{loanId}
URI Parameters
  • loanId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "title": "Loan",
  "description": "Links the item with the patron and applies certain conditions based on policies",
  "properties": {
    "id": {
      "description": "Unique ID (generated UUID) of the loan",
      "type": "string"
    },
    "userId": {
      "description": "ID of the patron the item was lent to. Required for open loans, not required for closed loans (for anonymization).",
      "type": "string"
    },
    "proxyUserId": {
      "description": "ID of the user representing a proxy for the patron",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "itemId": {
      "description": "ID of the item lent to the patron",
      "type": "string"
    },
    "loanPolicyId": {
      "description": "ID of last policy used in relation to this loan",
      "type": "string"
    },
    "item": {
      "description": "Additional information about the item",
      "type": "object",
      "properties": {
        "id": {
          "description": "ID of the item",
          "type": "string"
        },
        "title": {
          "description": "The title of the item lent to the patron",
          "type": "string"
        },
        "callNumber" : {
          "description" : "The call number from the holdings record",
          "type": "string"
        },
        "materialType": {
          "description": "The material type from the item record",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "contributors": {
            "description": "Contributors from the instance record",
            "type": "array",
            "items" : {
              "type": "object",
              "properties" : {
                 "name" : {
                    "type" : "string"
                  }
              },
              "additionalProperties": false
          }
        },
        "holdingsRecordId": {
          "description": "The ID of the holdings for the item",
          "type": "string"
        },
        "instanceId": {
          "description": "The ID of the instance for the item",
          "type": "string"
        },
        "barcode": {
          "description": "The barcode of the item",
          "type": "string"
        },
        "location": {
          "description": "The effective location of the item",
          "type": "object",
          "properties": {
            "name": {
              "description": "The name of the location",
              "type": "string"
            }
          }
        },
        "status": {
          "description": "Overall status of the item",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        },
        "inTransitDestinationServicePointId": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "inTransitDestinationServicePoint": {
          "description": "Service point an item is intended to be transited to (should only be present when in transit)",
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        }
      }
    },
    "status": {
      "description": "Overall status of the loan",
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the status (currently can be any value, values commonly used are Open and Closed)",
          "type": "string"
        }
      }
    },
    "loanDate": {
      "description": "Date and time when the loan began",
      "type": "string",
      "format": "date-time"
    },
    "dueDate": {
      "description": "Date and time when the item is due to be returned",
      "type": "string",
      "format": "date-time"
    },
    "returnDate": {
      "description": "Date and time when the item was returned",
      "type": "string",
      "format": "date-time"
    },
    "systemReturnDate": {
      "description": "Date and time when return was processed",
      "type": "string",
      "format": "date-time"
    },
    "action": {
      "description": "Last action performed on a loan (currently can be any value, values commonly used are checkedout and checkedin)",
      "type": "string"
    },
    "renewalCount": {
      "description": "Count of how many times a loan has been renewed (incremented by the client)",
      "type": "integer"
    },
    "checkoutServicePointId": {
      "description": "ID of the Service Point where the last checkout occured",
      "type": "string"
    },
    "checkinServicePointId": {
      "description": "ID of the Service Point where the last checkin occured",
      "type": "string"
    },
    "checkoutServicePoint": {
      "description": "The Service Point where the last checkout occurred",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique name of the service point"
        },
        "code": {
          "description": "The short code for the service point",
          "type": "string"
        },
        "discoveryDisplayName":{
          "description": "The human readable name",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "The time to shelving",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this a pickup location",
          "type": "boolean"
        }
      }
    },
    "checkinServicePoint": {
      "description": "The Service Point where the last checkout occurred",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The unique name of the service point"
        },
        "code": {
          "description": "The short code for the service point",
          "type": "string"
        },
        "discoveryDisplayName":{
          "description": "The human readable name",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "The time to shelving",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this a pickup location",
          "type": "boolean"
        }
      }
    },
    "metadata": {
      "description": "Metadata about creation and changes to loan, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "required": [
    "itemId",
    "loanDate",
    "action"
  ]
}

Example:

{
  "id": "cf23adf0-61ba-4887-bf82-956c4aae2260",
  "userId": "df7f4993-8c14-4a0f-ab63-93975ab01c76",
  "proxyUserId": "346ad017-dac1-417d-9ed8-0ac7eeb886aa",
  "itemId": "cb20f34f-b773-462f-a091-b233cc96b9e6",
  "item": {
    "title": "The Long Way to a Small, Angry Planet",
    "barcode": "036000291452",
    "status": {
      "name": "Checked Out"
    },
    "location": {
      "name": "Main Library"
    },
    "materialType": {
      "name": "Book"
    },
    "contributors": [
      {
        "name": "Steve Jones"
      }
    ]
  },
  "loanDate": "2017-03-01T23:11:00.000Z",
  "dueDate": "2017-04-01T23:11:00.000Z",
  "checkoutServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "checkinServicePointId": "e9af4ba4-6801-4722-bf45-d7a49d54564d",
  "status": {
    "name": "Open"
  },
  "action": "checkedout",
  "renewalCount": 0
}

Response 204

Item successfully updated

Response 400

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

Media type: text/plain

Type: any

Example:

"unable to update loan -- malformed JSON at 13:4"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"loan not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

Response 501

Not implemented yet

DELETE /circulation/loans/{loanId}

Delete loan item with given {loanId}

DELETE /circulation/loans/{loanId}
URI Parameters
  • loanId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 204

Item deleted successfully

Response 400

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

Media type: text/plain

Type: any

Example:

"unable to delete loan -- constraint violation"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"loan not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

Response 501

Not implemented yet

GET /circulation/loan-rules

Get the loan rules

GET /circulation/loan-rules

Response 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Loan Rules Schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "loanRulesAsTextFile": {
      "type": "string"
    },
    "loanRulesAsDrools": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "loanRulesAsTextFile",
    "loanRulesAsDrools"
  ]
}

Example:

{
  "loanRulesAsTextFile": "fallback-policy: ffffffff-2222-4b5e-a7bd-064b8d177231\\nm aaaaaaaa-1111-4b5e-a7bd-064b8d177231: ffffffff-3333-4b5e-a7bd-064b8d177231\\n    g cccccccc-1111-4b5e-a7bd-064b8d177231: ffffffff-4444-4b5e-a7bd-064b8d177231",
  "loanRulesAsDrools": "package loanrules\\nimport org.folio.circulation.loanrules.*\\nglobal LoanPolicy loanPolicy\\n\\n// fallback-policy\\nrule \"line 0\"\\n  salience 0\\n  when\\n  then\\n    loanPolicy.id = \"ffffffff-2222-4b5e-a7bd-064b8d177231\";\\n    drools.halt();\\nend\\n\\nrule \"line 1\"\\n  salience 1\\n  when\\n    ItemType(id == \"aaaaaaaa-1111-4b5e-a7bd-064b8d177231\")\\n  then\\n    loanPolicy.id = \"ffffffff-3333-4b5e-a7bd-064b8d177231\";\\n    drools.halt();\\nend\\n\\nrule \"line 2\"\\n  salience 2\\n  when\\n    ItemType(id == \"aaaaaaaa-1111-4b5e-a7bd-064b8d177231\")\\n    PatronGroup(id == \"cccccccc-1111-4b5e-a7bd-064b8d177231\")\\n  then\\n    loanPolicy.id = \"ffffffff-4444-4b5e-a7bd-064b8d177231\";\\n    drools.halt();\\nend"
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

PUT /circulation/loan-rules

Set the loan rules using a text file

PUT /circulation/loan-rules
Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Loan Rules Text Only Schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "loanRulesAsTextFile": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "loanRulesAsTextFile"
  ]
}

Example:

{
  "loanRulesAsTextFile": "fallback-policy: ffffffff-2222-4b5e-a7bd-064b8d177231\\nm aaaaaaaa-1111-4b5e-a7bd-064b8d177231: ffffffff-3333-4b5e-a7bd-064b8d177231\\n    g cccccccc-1111-4b5e-a7bd-064b8d177231: ffffffff-4444-4b5e-a7bd-064b8d177231"
}

Response 204

Loan rules have been saved.

Response 422

Validation error in the text file.

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Loan Rules Error Schema",
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "line": {
      "type": "integer"
    },
    "column": {
      "type": "integer"
    }
  },
  "additionalProperties": false,
  "required": [
    "message",
    "line",
    "column"
  ]
}

Example:

{
  "message": "One of the keywords t, a, b, c, s, m, g, fallback-policy, priority or the character # expected, but found: foobar",
  "line": 1,
  "column": 1
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

GET /circulation/loan-rules/apply

Get the loan policy when applying loan rules

GET /circulation/loan-rules/apply
Query Parameters
  • item_type_id: required (string - 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}$)

    Item type id

  • loan_type_id: required (string - 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}$)

    Loan type id

  • patron_type_id: required (string - 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}$)

    Patron type id

  • shelving_location_id: required (string - 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}$)

    Shelving location id

Response 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Loan policy id schema",
  "type": "object",
  "properties": {
    "loanPolicyId": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "loanPolicyId"
  ]
}

Example:

{
  "loanPolicyId": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231"
}

Response 400

Invalid query parameters

Body

Media type: text/plain

Type: any

Example:

required query parameter missing: item_type_id

Response 422

Invalid id error.

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An error",
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "parameters": {
      "type": "object",
      "$ref": "parameters.schema"
    }
  },
  "required": [
    "message"
  ]
}

Example:

{
  "message": "Patron type id does not exist: 99"
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

GET /circulation/loan-rules/apply-all

Get loan rule and loan policy for each match when applying loan rules

GET /circulation/loan-rules/apply-all
Query Parameters
  • item_type_id: required (string - 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}$)

    Item type id

  • loan_type_id: required (string - 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}$)

    Loan type id

  • patron_type_id: required (string - 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}$)

    Patron type id

  • shelving_location_id: required (string - 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}$)

    Shelving location id

  • loan_rules: (string)

    Loan rules if provided, otherwise use stored loan rules

Response 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Loan policy ids schema",
  "type": "object",
  "properties": {
    "loanRuleMatches": {
      "id": "loanRuleMatches",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "loan-rule-match.json"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "loanRuleMatches"
  ]
}

Example:

{
  "loanRuleMatches": [
    {
      "loanRuleLine": 7,
      "loanPolicyId": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231"
    },
    {
      "loanRuleLine": 4,
      "loanPolicyId": "5e3bf628-cf74-48c2-ae8e-fe1bdc8d6220"
    },
    {
      "loanRuleLine": 1,
      "loanPolicyId": "7df77ebc-6dd3-425c-a00a-82c1ae930f72"
    }
  ]
}

Response 422

Invalid id error.

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An error",
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "parameters": {
      "type": "object",
      "$ref": "parameters.schema"
    }
  },
  "required": [
    "message"
  ]
}

Example:

{
  "message": "Patron type id does not exist: 99"
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

GET /circulation/requests

Retrieve a list of request items.

GET /circulation/requests
Query Parameters
  • offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)

    Skip over a number of elements by specifying an offset value for the query

    Example:

    0
  • limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)

    Limit the number of elements returned in the response

    Example:

    10
  • query: (string)

    A query expressed as a CQL string (see dev.folio.org/reference/glossary#cql) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.

    by using CQL

    Example:

    (username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
    
    requesterId="cf23adf0-61ba-4887-bf82-956c4aae2260"
    
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns a list of request items

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "requests": {
      "id": "requests",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "request.json"
      }
    },
    "totalRecords": {
      "type": "integer"
    }
  },
  "required": [
    "requests",
    "totalRecords"
  ]
}

Example:

{
  "requests": [
    {
      "id": "89105c06-dbdb-4aa0-9695-d4d19c733270",
      "requestType": "Recall",
      "requestDate": "2017-07-29T22:25:37Z",
      "requesterId": "21932a85-bd00-446b-9565-46e0c1a5490b",
      "itemId": "195efae1-588f-47bd-a181-13a2eb437701",
      "fulfilmentPreference": "Hold Shelf",
      "position": 1
    },
    {
      "id": "f5cec279-0da6-4b44-a3df-f49b0903f325",
      "requestType": "Hold",
      "requestDate": "2017-08-05T11:43:23Z",
      "requesterId": "61d939e4-f2ae-4c53-95d2-224a802fa2a6",
      "itemId": "3e5d5433-a271-499c-94f4-5f3e4652e537",
      "fulfilmentPreference": "Delivery",
      "requestExpirationDate": "2017-08-31",
      "holdShelfExpirationDate": "2017-09-01",
      "position": 1,
      "item": {
        "title": "Children of Time",
        "barcode": "760932543816"
      },
      "requester": {
        "firstName": "Stephen",
        "lastName": "Jones",
        "middleName": "Anthony",
        "barcode": "567023127436"
      }
    }
  ],
  "totalRecords": 2
}

Response 400

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

Media type: text/plain

Type: any

Example:

unable to list requests -- malformed parameter 'query', syntax error at column 6

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to list requests -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

Response 501

Not implemented yet

POST /circulation/requests

Create a new request item.

POST /circulation/requests
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of the request",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "requestType": {
      "description": "Whether the item should be held upon return, recalled or paged for",
      "type": "string",
      "enum": ["Hold", "Recall", "Page"]
    },
    "requestDate": {
      "description": "Date the request was made",
      "type": "string",
      "format": "date-time"
    },
    "requesterId": {
      "description": "ID of the user who made the request",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "proxyUserId": {
      "description": "ID of the user representing a proxy for the patron",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "itemId": {
      "description": "ID of the item being requested",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "status": {
      "description": "Status of the request",
      "type": "string",
      "enum": [
        "Open - Not yet filled",
        "Open - Awaiting pickup",
        "Closed - Filled",
        "Closed - Cancelled"
      ]
    },
    "cancellationReasonId": {
      "description": "The id of the request reason",
      "type": "string"
    },
    "cancelledByUserId": {
      "description": "The id of the user that cancelled the request",
      "type": "string"
    },
    "cancellationAdditionalInformation": {
      "description": "Additional information about a cancellation",
      "type": "string"
    },
    "cancelledDate": {
      "description": "Date the request was cancelled",
      "type": "string",
      "format": "date-time"
    },
    "position": {
      "description": "position of the request in a per-item request queue",
      "type": "integer"
    },
    "item": {
      "description": "Information about the requested item (some of which is stored and used for searching and sorting)",
      "readOnly": true,
      "type": "object",
      "properties": {
        "title": {
          "description": "title of the item (stored)",
          "type": "string",
          "readonly": true
        },
        "barcode": {
          "description": "barcode of the item (stored)",
          "type": "string",
          "readonly": true
        },
        "holdingsRecordId": {
          "description": "The ID of the holdings for the item",
          "type": "string",
          "readonly": true
        },
        "instanceId": {
          "description": "The ID of the instance for the item",
          "type": "string",
          "readonly": true
        },
        "location": {
          "description": "The effective location of the item",
          "type": "object",
          "readonly": true,
          "properties": {
            "name": {
              "type": "string",
              "description": "The name of the location",
              "readonly": true
            }
          }
        },
        "contributorNames": {
          "description": "A list of contributor names",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "description": "The contributor name",
                "type": "string"
              }
            }
          }
        }
      },
      "additionalProperties": false
    },
    "requester": {
      "description": "Copy of some requesting patron metadata (used for searching and sorting), will be taken from the user referred to by the requesterId",
      "readonly": true,
      "type": "object",
      "properties": {
        "firstName": {
          "description": "first name of the patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "lastName": {
          "description": "last name of the patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "middleName": {
          "description": "middle name of the patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "barcode": {
          "description": "barcode of the patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "patronGroupId": {
          "description": "UUID for the patron group that this user belongs to",
          "type": "string"
        },
        "patronGroup": {
          "description": "record for the user's patron group",
          "type": "object",
          "properties": {
            "id": {
              "description": "ID of the patron group",
              "type": "string"
            },
            "group": {
              "description": "The unique name of the patron group",
              "type": "string"
            },
            "desc": {
              "description": "A description of the patron group",
              "type": "string"
            }
          }
        }
      },
      "additionalProperties": false
    },
    "proxy": {
      "description": "Copy of some proxy patron metadata (used for searching and sorting), will be taken from the user referred to by the proxyUserId",
      "readonly": true,
      "type": "object",
      "properties": {
        "firstName": {
          "description": "first name of the proxy patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "lastName": {
          "description": "last name of the proxy patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "middleName": {
          "description": "middle name of the proxy patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "barcode": {
          "description": "barcode of the proxy patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "patronGroupId": {
          "description": "UUID for the patrongroup that this user belongs to",
          "type": "string"
        },
        "patronGroup": {
          "description": "record for the user's patrongroup",
          "type": "object",
          "properties": {
            "id": {
              "description": "ID of the patrongroup",
              "type": "string"
            },
            "group": {
              "description": "The unique name of the patrongroup",
              "type": "string"
            },
            "desc": {
              "description": "A description of the patrongroup",
              "type": "string"
            }
          }
        }
      },
      "additionalProperties": false
    },
    "fulfilmentPreference": {
      "description": "How should the request be fulfilled (whether the item should be kept on the hold shelf for collection or delivered to the requester)",
      "type": "string",
      "enum": ["Hold Shelf", "Delivery"]
    },
    "deliveryAddressTypeId": {
      "description": "Deliver to the address of this type, for the requesting patron",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "deliveryAddress": {
      "description": "Address the item is to be delivered to (derived from requester information)",
      "type": "object",
      "properties": {
        "addressLine1": {
          "description": "Address line 1",
          "type": "string"
        },
        "addressLine2": {
          "description": "Address line 2",
          "type": "string"
        },
        "city": {
          "description": "City name",
          "type": "string"
        },
        "region": {
          "description": "Region",
          "type": "string"
        },
        "postalCode": {
          "description": "Postal code",
          "type": "string"
        },
        "countryId": {
          "description": "Country code",
          "type": "string"
        },
        "addressTypeId": {
          "description": "Type of address (refers to address types)",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "requestExpirationDate": {
      "description": "Date when the request expires",
      "type": "string",
      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
    },
    "holdShelfExpirationDate": {
      "description": "Date when an item returned to the hold shelf expires",
      "type": "string",
      "pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}"
    },
    "pickupServicePointId": {
      "description": "The ID of the Service Point where this request can be picked up",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "pickupServicePoint": {
      "description": "The full object of the Service Point record from pickupServicePointId",
      "properties": {
        "name": {
          "description": "Unique name for the service point",
          "type": "string"
        },
        "code": {
          "description": "Unique code for the service point",
          "type": "string"
        },
        "discoveryDisplayName": {
          "description": "Human-readable name for the service point",
          "type": "string"
        },
        "description": {
          "description": "Description of the service point",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "Shelving lag time",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this service point a pickup location?",
          "type": "boolean"
        }
      }
    },
    "metadata": {
      "description": "Metadata about creation and changes to requests, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "additionalProperties": false,
  "required": [
    "itemId",
    "requesterId",
    "requestType",
    "requestDate",
    "fulfilmentPreference"
  ]
}

Example:

{
  "id": "89105c06-dbdb-4aa0-9695-d4d19c733270",
  "requestType": "Recall",
  "requestDate": "2017-07-29T22:25:37Z",
  "requesterId": "21932a85-bd00-446b-9565-46e0c1a5490b",
  "itemId": "195efae1-588f-47bd-a181-13a2eb437701",
  "fulfilmentPreference": "Hold Shelf",
  "requestExpirationDate": "2017-07-25",
  "position": 1,
  "item": {
    "location": {
      "name": "Main Library"
    }
  }
}

Response 201

Returns a newly created item, with server-controlled fields like 'id' populated

Headers
  • Location: required (string)

    URI to the created request item

Body

Media type: application/json

Type: any

Example:

{
  "id": "89105c06-dbdb-4aa0-9695-d4d19c733270",
  "requestType": "Recall",
  "requestDate": "2017-07-29T22:25:37Z",
  "requesterId": "21932a85-bd00-446b-9565-46e0c1a5490b",
  "itemId": "195efae1-588f-47bd-a181-13a2eb437701",
  "fulfilmentPreference": "Hold Shelf",
  "requestExpirationDate": "2017-07-25",
  "position": 1,
  "item": {
    "location": {
      "name": "Main Library"
    }
  }
}

Response 400

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

Media type: text/plain

Type: any

Example:

"unable to add request -- malformed JSON at 13:3"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create requests -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

Response 501

Not implemented yet

DELETE /circulation/requests

DELETE /circulation/requests
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 204

All requests deleted

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

Response 501

Not implemented yet

GET /circulation/requests/{requestId}

Retrieve request item with given {requestId}

GET /circulation/requests/{requestId}
URI Parameters
  • requestId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns item with a given ID

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of the request",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "requestType": {
      "description": "Whether the item should be held upon return, recalled or paged for",
      "type": "string",
      "enum": ["Hold", "Recall", "Page"]
    },
    "requestDate": {
      "description": "Date the request was made",
      "type": "string",
      "format": "date-time"
    },
    "requesterId": {
      "description": "ID of the user who made the request",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "proxyUserId": {
      "description": "ID of the user representing a proxy for the patron",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "itemId": {
      "description": "ID of the item being requested",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "status": {
      "description": "Status of the request",
      "type": "string",
      "enum": [
        "Open - Not yet filled",
        "Open - Awaiting pickup",
        "Closed - Filled",
        "Closed - Cancelled"
      ]
    },
    "cancellationReasonId": {
      "description": "The id of the request reason",
      "type": "string"
    },
    "cancelledByUserId": {
      "description": "The id of the user that cancelled the request",
      "type": "string"
    },
    "cancellationAdditionalInformation": {
      "description": "Additional information about a cancellation",
      "type": "string"
    },
    "cancelledDate": {
      "description": "Date the request was cancelled",
      "type": "string",
      "format": "date-time"
    },
    "position": {
      "description": "position of the request in a per-item request queue",
      "type": "integer"
    },
    "item": {
      "description": "Information about the requested item (some of which is stored and used for searching and sorting)",
      "readOnly": true,
      "type": "object",
      "properties": {
        "title": {
          "description": "title of the item (stored)",
          "type": "string",
          "readonly": true
        },
        "barcode": {
          "description": "barcode of the item (stored)",
          "type": "string",
          "readonly": true
        },
        "holdingsRecordId": {
          "description": "The ID of the holdings for the item",
          "type": "string",
          "readonly": true
        },
        "instanceId": {
          "description": "The ID of the instance for the item",
          "type": "string",
          "readonly": true
        },
        "location": {
          "description": "The effective location of the item",
          "type": "object",
          "readonly": true,
          "properties": {
            "name": {
              "type": "string",
              "description": "The name of the location",
              "readonly": true
            }
          }
        },
        "contributorNames": {
          "description": "A list of contributor names",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "description": "The contributor name",
                "type": "string"
              }
            }
          }
        }
      },
      "additionalProperties": false
    },
    "requester": {
      "description": "Copy of some requesting patron metadata (used for searching and sorting), will be taken from the user referred to by the requesterId",
      "readonly": true,
      "type": "object",
      "properties": {
        "firstName": {
          "description": "first name of the patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "lastName": {
          "description": "last name of the patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "middleName": {
          "description": "middle name of the patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "barcode": {
          "description": "barcode of the patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "patronGroupId": {
          "description": "UUID for the patron group that this user belongs to",
          "type": "string"
        },
        "patronGroup": {
          "description": "record for the user's patron group",
          "type": "object",
          "properties": {
            "id": {
              "description": "ID of the patron group",
              "type": "string"
            },
            "group": {
              "description": "The unique name of the patron group",
              "type": "string"
            },
            "desc": {
              "description": "A description of the patron group",
              "type": "string"
            }
          }
        }
      },
      "additionalProperties": false
    },
    "proxy": {
      "description": "Copy of some proxy patron metadata (used for searching and sorting), will be taken from the user referred to by the proxyUserId",
      "readonly": true,
      "type": "object",
      "properties": {
        "firstName": {
          "description": "first name of the proxy patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "lastName": {
          "description": "last name of the proxy patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "middleName": {
          "description": "middle name of the proxy patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "barcode": {
          "description": "barcode of the proxy patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "patronGroupId": {
          "description": "UUID for the patrongroup that this user belongs to",
          "type": "string"
        },
        "patronGroup": {
          "description": "record for the user's patrongroup",
          "type": "object",
          "properties": {
            "id": {
              "description": "ID of the patrongroup",
              "type": "string"
            },
            "group": {
              "description": "The unique name of the patrongroup",
              "type": "string"
            },
            "desc": {
              "description": "A description of the patrongroup",
              "type": "string"
            }
          }
        }
      },
      "additionalProperties": false
    },
    "fulfilmentPreference": {
      "description": "How should the request be fulfilled (whether the item should be kept on the hold shelf for collection or delivered to the requester)",
      "type": "string",
      "enum": ["Hold Shelf", "Delivery"]
    },
    "deliveryAddressTypeId": {
      "description": "Deliver to the address of this type, for the requesting patron",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "deliveryAddress": {
      "description": "Address the item is to be delivered to (derived from requester information)",
      "type": "object",
      "properties": {
        "addressLine1": {
          "description": "Address line 1",
          "type": "string"
        },
        "addressLine2": {
          "description": "Address line 2",
          "type": "string"
        },
        "city": {
          "description": "City name",
          "type": "string"
        },
        "region": {
          "description": "Region",
          "type": "string"
        },
        "postalCode": {
          "description": "Postal code",
          "type": "string"
        },
        "countryId": {
          "description": "Country code",
          "type": "string"
        },
        "addressTypeId": {
          "description": "Type of address (refers to address types)",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "requestExpirationDate": {
      "description": "Date when the request expires",
      "type": "string",
      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
    },
    "holdShelfExpirationDate": {
      "description": "Date when an item returned to the hold shelf expires",
      "type": "string",
      "pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}"
    },
    "pickupServicePointId": {
      "description": "The ID of the Service Point where this request can be picked up",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "pickupServicePoint": {
      "description": "The full object of the Service Point record from pickupServicePointId",
      "properties": {
        "name": {
          "description": "Unique name for the service point",
          "type": "string"
        },
        "code": {
          "description": "Unique code for the service point",
          "type": "string"
        },
        "discoveryDisplayName": {
          "description": "Human-readable name for the service point",
          "type": "string"
        },
        "description": {
          "description": "Description of the service point",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "Shelving lag time",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this service point a pickup location?",
          "type": "boolean"
        }
      }
    },
    "metadata": {
      "description": "Metadata about creation and changes to requests, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "additionalProperties": false,
  "required": [
    "itemId",
    "requesterId",
    "requestType",
    "requestDate",
    "fulfilmentPreference"
  ]
}

Example:

{
  "id": "89105c06-dbdb-4aa0-9695-d4d19c733270",
  "requestType": "Recall",
  "requestDate": "2017-07-29T22:25:37Z",
  "requesterId": "21932a85-bd00-446b-9565-46e0c1a5490b",
  "itemId": "195efae1-588f-47bd-a181-13a2eb437701",
  "fulfilmentPreference": "Hold Shelf",
  "requestExpirationDate": "2017-07-25",
  "position": 1,
  "item": {
    "location": {
      "name": "Main Library"
    }
  }
}

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"request not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

Response 501

Not implemented yet

PUT /circulation/requests/{requestId}

Update request item with given {requestId}

PUT /circulation/requests/{requestId}
URI Parameters
  • requestId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of the request",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "requestType": {
      "description": "Whether the item should be held upon return, recalled or paged for",
      "type": "string",
      "enum": ["Hold", "Recall", "Page"]
    },
    "requestDate": {
      "description": "Date the request was made",
      "type": "string",
      "format": "date-time"
    },
    "requesterId": {
      "description": "ID of the user who made the request",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "proxyUserId": {
      "description": "ID of the user representing a proxy for the patron",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "itemId": {
      "description": "ID of the item being requested",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "status": {
      "description": "Status of the request",
      "type": "string",
      "enum": [
        "Open - Not yet filled",
        "Open - Awaiting pickup",
        "Closed - Filled",
        "Closed - Cancelled"
      ]
    },
    "cancellationReasonId": {
      "description": "The id of the request reason",
      "type": "string"
    },
    "cancelledByUserId": {
      "description": "The id of the user that cancelled the request",
      "type": "string"
    },
    "cancellationAdditionalInformation": {
      "description": "Additional information about a cancellation",
      "type": "string"
    },
    "cancelledDate": {
      "description": "Date the request was cancelled",
      "type": "string",
      "format": "date-time"
    },
    "position": {
      "description": "position of the request in a per-item request queue",
      "type": "integer"
    },
    "item": {
      "description": "Information about the requested item (some of which is stored and used for searching and sorting)",
      "readOnly": true,
      "type": "object",
      "properties": {
        "title": {
          "description": "title of the item (stored)",
          "type": "string",
          "readonly": true
        },
        "barcode": {
          "description": "barcode of the item (stored)",
          "type": "string",
          "readonly": true
        },
        "holdingsRecordId": {
          "description": "The ID of the holdings for the item",
          "type": "string",
          "readonly": true
        },
        "instanceId": {
          "description": "The ID of the instance for the item",
          "type": "string",
          "readonly": true
        },
        "location": {
          "description": "The effective location of the item",
          "type": "object",
          "readonly": true,
          "properties": {
            "name": {
              "type": "string",
              "description": "The name of the location",
              "readonly": true
            }
          }
        },
        "contributorNames": {
          "description": "A list of contributor names",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "description": "The contributor name",
                "type": "string"
              }
            }
          }
        }
      },
      "additionalProperties": false
    },
    "requester": {
      "description": "Copy of some requesting patron metadata (used for searching and sorting), will be taken from the user referred to by the requesterId",
      "readonly": true,
      "type": "object",
      "properties": {
        "firstName": {
          "description": "first name of the patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "lastName": {
          "description": "last name of the patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "middleName": {
          "description": "middle name of the patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "barcode": {
          "description": "barcode of the patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "patronGroupId": {
          "description": "UUID for the patron group that this user belongs to",
          "type": "string"
        },
        "patronGroup": {
          "description": "record for the user's patron group",
          "type": "object",
          "properties": {
            "id": {
              "description": "ID of the patron group",
              "type": "string"
            },
            "group": {
              "description": "The unique name of the patron group",
              "type": "string"
            },
            "desc": {
              "description": "A description of the patron group",
              "type": "string"
            }
          }
        }
      },
      "additionalProperties": false
    },
    "proxy": {
      "description": "Copy of some proxy patron metadata (used for searching and sorting), will be taken from the user referred to by the proxyUserId",
      "readonly": true,
      "type": "object",
      "properties": {
        "firstName": {
          "description": "first name of the proxy patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "lastName": {
          "description": "last name of the proxy patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "middleName": {
          "description": "middle name of the proxy patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "barcode": {
          "description": "barcode of the proxy patron (read only, defined by the server)",
          "type": "string",
          "readonly": true
        },
        "patronGroupId": {
          "description": "UUID for the patrongroup that this user belongs to",
          "type": "string"
        },
        "patronGroup": {
          "description": "record for the user's patrongroup",
          "type": "object",
          "properties": {
            "id": {
              "description": "ID of the patrongroup",
              "type": "string"
            },
            "group": {
              "description": "The unique name of the patrongroup",
              "type": "string"
            },
            "desc": {
              "description": "A description of the patrongroup",
              "type": "string"
            }
          }
        }
      },
      "additionalProperties": false
    },
    "fulfilmentPreference": {
      "description": "How should the request be fulfilled (whether the item should be kept on the hold shelf for collection or delivered to the requester)",
      "type": "string",
      "enum": ["Hold Shelf", "Delivery"]
    },
    "deliveryAddressTypeId": {
      "description": "Deliver to the address of this type, for the requesting patron",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "deliveryAddress": {
      "description": "Address the item is to be delivered to (derived from requester information)",
      "type": "object",
      "properties": {
        "addressLine1": {
          "description": "Address line 1",
          "type": "string"
        },
        "addressLine2": {
          "description": "Address line 2",
          "type": "string"
        },
        "city": {
          "description": "City name",
          "type": "string"
        },
        "region": {
          "description": "Region",
          "type": "string"
        },
        "postalCode": {
          "description": "Postal code",
          "type": "string"
        },
        "countryId": {
          "description": "Country code",
          "type": "string"
        },
        "addressTypeId": {
          "description": "Type of address (refers to address types)",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "requestExpirationDate": {
      "description": "Date when the request expires",
      "type": "string",
      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
    },
    "holdShelfExpirationDate": {
      "description": "Date when an item returned to the hold shelf expires",
      "type": "string",
      "pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}"
    },
    "pickupServicePointId": {
      "description": "The ID of the Service Point where this request can be picked up",
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "pickupServicePoint": {
      "description": "The full object of the Service Point record from pickupServicePointId",
      "properties": {
        "name": {
          "description": "Unique name for the service point",
          "type": "string"
        },
        "code": {
          "description": "Unique code for the service point",
          "type": "string"
        },
        "discoveryDisplayName": {
          "description": "Human-readable name for the service point",
          "type": "string"
        },
        "description": {
          "description": "Description of the service point",
          "type": "string"
        },
        "shelvingLagTime": {
          "description": "Shelving lag time",
          "type": "integer"
        },
        "pickupLocation": {
          "description": "Is this service point a pickup location?",
          "type": "boolean"
        }
      }
    },
    "metadata": {
      "description": "Metadata about creation and changes to requests, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "raml-util/schemas/metadata.schema"
    }
  },
  "additionalProperties": false,
  "required": [
    "itemId",
    "requesterId",
    "requestType",
    "requestDate",
    "fulfilmentPreference"
  ]
}

Example:

{
  "id": "89105c06-dbdb-4aa0-9695-d4d19c733270",
  "requestType": "Recall",
  "requestDate": "2017-07-29T22:25:37Z",
  "requesterId": "21932a85-bd00-446b-9565-46e0c1a5490b",
  "itemId": "195efae1-588f-47bd-a181-13a2eb437701",
  "fulfilmentPreference": "Hold Shelf",
  "requestExpirationDate": "2017-07-25",
  "position": 1,
  "item": {
    "location": {
      "name": "Main Library"
    }
  }
}

Response 204

Item successfully updated

Response 400

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

Media type: text/plain

Type: any

Example:

"unable to update request -- malformed JSON at 13:4"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"request not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

Response 501

Not implemented yet

DELETE /circulation/requests/{requestId}

Delete request item with given {requestId}

DELETE /circulation/requests/{requestId}
URI Parameters
  • requestId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 204

Item deleted successfully

Response 400

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

Media type: text/plain

Type: any

Example:

"unable to delete request -- constraint violation"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"request not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

Response 501

Not implemented yet

GET /circulation/requests/queue/{itemId}

Retrieve queue item with given {queueId}

GET /circulation/requests/queue/{itemId}
URI Parameters
  • itemId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns item with a given ID

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "requests": {
      "id": "requests",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "request.json"
      }
    },
    "totalRecords": {
      "type": "integer"
    }
  },
  "required": [
    "requests",
    "totalRecords"
  ]
}

Example:

{
  "requests": [
    {
      "id": "89105c06-dbdb-4aa0-9695-d4d19c733270",
      "requestType": "Recall",
      "requestDate": "2017-07-29T22:25:37Z",
      "requesterId": "21932a85-bd00-446b-9565-46e0c1a5490b",
      "itemId": "195efae1-588f-47bd-a181-13a2eb437701",
      "fulfilmentPreference": "Hold Shelf",
      "position": 1
    },
    {
      "id": "f5cec279-0da6-4b44-a3df-f49b0903f325",
      "requestType": "Hold",
      "requestDate": "2017-08-05T11:43:23Z",
      "requesterId": "61d939e4-f2ae-4c53-95d2-224a802fa2a6",
      "itemId": "195efae1-588f-47bd-a181-13a2eb437701",
      "fulfilmentPreference": "Delivery",
      "position": 2
    },
    {
      "id": "666e788f-1d9c-4846-b347-c40e711153fb",
      "requestType": "Hold",
      "requestDate": "2018-01-02T16:35:27Z",
      "requesterId": "08876b22-8572-4b35-b25e-afc45c8e6e61",
      "itemId": "195efae1-588f-47bd-a181-13a2eb437701",
      "fulfilmentPreference": "Hold Shelf",
      "position": 3
    }
  ],
  "totalRecords": 2
}

Response 400

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

Media type: text/plain

Type: any

Example:

"unable to list queue -- malformed parameter 'query', syntax error at column 6"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

"unable to list queue -- unauthorized"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"queue not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator