http://github.com/org/folio/mod-inventory-storage
This documents the API calls that can be made to query and manage location units like institutions, campuses, and libraries
Return a list of institutions
GET /location-units/institutions
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.
with valid searchable fields
Example:
(username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
name=aaa
How to calculate the totalRecords property. "exact" for the correct number, "estimated" for an estimation, "auto" to automatically select "exact" or "estimated", "none" for suppressing the totalRecords property. For details see https://github.com/folio-org/raml-module-builder#estimated-totalrecords
Example:
none
Skip over a number of elements by specifying an offset value for the query
Example:
0
Limit the number of elements returned in the response. Using limit=0 will return totalRecords with the exact value. For details about totalRecords see https://github.com/folio-org/raml-module-builder#estimated-totalrecords
Example:
10
Returns a list of institution items
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A collection of top-level location units",
"type": "object",
"properties": {
"locinsts": {
"description": "List of first-level location units",
"id": "locinsts",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "highest-level location unit",
"properties": {
"id": {
"type": "string"
},
"name": {
"description": "name of location",
"type": "string"
},
"code": {
"description": "distinct code for location",
"type": "string"
},
"metadata": {
"type": "object",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"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}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"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}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"additionalProperties": false,
"required": [
"name",
"code"
]
}
},
"totalRecords": {
"description": "Estimated or exact total number of records",
"type": "integer"
}
},
"required": [
"locinsts",
"totalRecords"
]
}
Example:
{
"locinsts": [
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Main Library",
"code": "ML"
},
{
"id": "0df935eb-f3f4-4741-9ac6-33c500174b96",
"name": "Agriculture Library Reserve",
"code": "ALR"
}
],
"totalRecords": 2
}
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.
Media type: text/plain
Type: any
Example:
unable to list institutions -- malformed parameter 'query', syntax error at column 6
Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to list institutions -- unauthorized
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
Create a new institution
POST /location-units/institutions
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "highest-level location unit",
"properties": {
"id": {
"type": "string"
},
"name": {
"description": "name of location",
"type": "string"
},
"code": {
"description": "distinct code for location",
"type": "string"
},
"metadata": {
"type": "object",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"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}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"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}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"additionalProperties": false,
"required": [
"name",
"code"
]
}
Example:
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Main Library",
"code": "ML"
}
Returns a newly created item, with server-controlled fields like 'id' populated
URI to the created institution item
Media type: application/json
Type: any
Example:
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Main Library",
"code": "ML"
}
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.
Media type: text/plain
Type: any
Example:
"unable to add institution -- malformed JSON at 13:3"
Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to create institutions -- unauthorized
Validation errors
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Example:
{
"errors": [
{
"message": "may not be null",
"type": "1",
"code": "-1",
"parameters": [
{
"key": "moduleTo",
"value": "null"
}
]
}
]
}
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
Delete all institutions
DELETE /location-units/institutions
All institutions deleted
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
Retrieve institution item with given {institutionId}
GET /location-units/institutions/{id}
Returns item with a given ID
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "highest-level location unit",
"properties": {
"id": {
"type": "string"
},
"name": {
"description": "name of location",
"type": "string"
},
"code": {
"description": "distinct code for location",
"type": "string"
},
"metadata": {
"type": "object",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"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}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"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}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"additionalProperties": false,
"required": [
"name",
"code"
]
}
Example:
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Main Library",
"code": "ML"
}
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"institution not found"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
Update institution item with given {institutionId}
PUT /location-units/institutions/{id}
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "highest-level location unit",
"properties": {
"id": {
"type": "string"
},
"name": {
"description": "name of location",
"type": "string"
},
"code": {
"description": "distinct code for location",
"type": "string"
},
"metadata": {
"type": "object",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"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}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"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}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"additionalProperties": false,
"required": [
"name",
"code"
]
}
Example:
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Main Library",
"code": "ML"
}
Item successfully updated
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.
Media type: text/plain
Type: any
Example:
"unable to update institution -- malformed JSON at 13:4"
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"institution not found"
Optimistic locking version conflict
Media type: text/plain
Type: any
Example:
version conflict
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
Delete institution item with given {institutionId}
DELETE /location-units/institutions/{id}
Item deleted successfully
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.
Media type: text/plain
Type: any
Example:
"unable to delete institution -- constraint violation"
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"institution not found"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
Return a list of campuses
GET /location-units/campuses
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.
with valid searchable fields
Example:
(username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
name=aaa
How to calculate the totalRecords property. "exact" for the correct number, "estimated" for an estimation, "auto" to automatically select "exact" or "estimated", "none" for suppressing the totalRecords property. For details see https://github.com/folio-org/raml-module-builder#estimated-totalrecords
Example:
none
Skip over a number of elements by specifying an offset value for the query
Example:
0
Limit the number of elements returned in the response. Using limit=0 will return totalRecords with the exact value. For details about totalRecords see https://github.com/folio-org/raml-module-builder#estimated-totalrecords
Example:
10
Returns a list of campus items
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A collection of second-level location units",
"type": "object",
"properties": {
"loccamps": {
"description": "List of second-level location units",
"id": "loccamps",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "second-level location unit",
"properties": {
"id": {
"type": "string"
},
"name": {
"description": "name of the location",
"type": "string"
},
"code": {
"description": "distinct code for the location",
"type": "string"
},
"institutionId": {
"description": "ID of the first-level location unit that the second-level unit belongs to",
"type": "string"
},
"metadata": {
"type": "object",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"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}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"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}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"additionalProperties": false,
"required": [
"name",
"institutionId",
"code"
]
}
},
"totalRecords": {
"description": "Estimated or exact total number of records",
"type": "integer"
}
},
"required": [
"loccamps",
"totalRecords"
]
}
Example:
{
"loccamps": [
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Riverside Campus",
"code": "RS",
"institutionId": "559d83b1-1c81-4cc1-935f-8da45c1c4573"
},
{
"id": "0df935eb-f3f4-4741-9ac6-33c500174b96",
"name": "Other Side Campus",
"code": "OSC",
"institutionId": "559d83b1-1c81-4cc1-935f-8da45c1c4573"
}
],
"totalRecords": 2
}
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.
Media type: text/plain
Type: any
Example:
unable to list campuses -- malformed parameter 'query', syntax error at column 6
Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to list campuses -- unauthorized
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
Create a new campus
POST /location-units/campuses
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "second-level location unit",
"properties": {
"id": {
"type": "string"
},
"name": {
"description": "name of the location",
"type": "string"
},
"code": {
"description": "distinct code for the location",
"type": "string"
},
"institutionId": {
"description": "ID of the first-level location unit that the second-level unit belongs to",
"type": "string"
},
"metadata": {
"type": "object",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"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}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"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}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"additionalProperties": false,
"required": [
"name",
"institutionId",
"code"
]
}
Example:
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Riverside Campus",
"code": "RS",
"institutionId": "559d83b1-1c81-4cc1-935f-8da45c1c4573"
}
Returns a newly created item, with server-controlled fields like 'id' populated
URI to the created campus item
Media type: application/json
Type: any
Example:
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Riverside Campus",
"code": "RS",
"institutionId": "559d83b1-1c81-4cc1-935f-8da45c1c4573"
}
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.
Media type: text/plain
Type: any
Example:
"unable to add campus -- malformed JSON at 13:3"
Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to create campuses -- unauthorized
Validation errors
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Example:
{
"errors": [
{
"message": "may not be null",
"type": "1",
"code": "-1",
"parameters": [
{
"key": "moduleTo",
"value": "null"
}
]
}
]
}
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
Delete all campuses
DELETE /location-units/campuses
All campuses deleted
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
Retrieve campus item with given {campusId}
GET /location-units/campuses/{id}
Returns item with a given ID
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "second-level location unit",
"properties": {
"id": {
"type": "string"
},
"name": {
"description": "name of the location",
"type": "string"
},
"code": {
"description": "distinct code for the location",
"type": "string"
},
"institutionId": {
"description": "ID of the first-level location unit that the second-level unit belongs to",
"type": "string"
},
"metadata": {
"type": "object",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"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}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"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}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"additionalProperties": false,
"required": [
"name",
"institutionId",
"code"
]
}
Example:
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Riverside Campus",
"code": "RS",
"institutionId": "559d83b1-1c81-4cc1-935f-8da45c1c4573"
}
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"campus not found"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
Update campus item with given {campusId}
PUT /location-units/campuses/{id}
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "second-level location unit",
"properties": {
"id": {
"type": "string"
},
"name": {
"description": "name of the location",
"type": "string"
},
"code": {
"description": "distinct code for the location",
"type": "string"
},
"institutionId": {
"description": "ID of the first-level location unit that the second-level unit belongs to",
"type": "string"
},
"metadata": {
"type": "object",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"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}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"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}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"additionalProperties": false,
"required": [
"name",
"institutionId",
"code"
]
}
Example:
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Riverside Campus",
"code": "RS",
"institutionId": "559d83b1-1c81-4cc1-935f-8da45c1c4573"
}
Item successfully updated
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.
Media type: text/plain
Type: any
Example:
"unable to update campus -- malformed JSON at 13:4"
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"campus not found"
Optimistic locking version conflict
Media type: text/plain
Type: any
Example:
version conflict
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
Delete campus item with given {campusId}
DELETE /location-units/campuses/{id}
Item deleted successfully
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.
Media type: text/plain
Type: any
Example:
"unable to delete campus -- constraint violation"
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"campus not found"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
Return a list of libraries
GET /location-units/libraries
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.
with valid searchable fields
Example:
(username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
name=aaa
How to calculate the totalRecords property. "exact" for the correct number, "estimated" for an estimation, "auto" to automatically select "exact" or "estimated", "none" for suppressing the totalRecords property. For details see https://github.com/folio-org/raml-module-builder#estimated-totalrecords
Example:
none
Skip over a number of elements by specifying an offset value for the query
Example:
0
Limit the number of elements returned in the response. Using limit=0 will return totalRecords with the exact value. For details about totalRecords see https://github.com/folio-org/raml-module-builder#estimated-totalrecords
Example:
10
Returns a list of library items
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A collection of third-level location units",
"type": "object",
"properties": {
"loclibs": {
"description": "List of third-level location units",
"id": "loclibs",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "third-level location unit",
"properties": {
"id": {
"type": "string"
},
"name": {
"description": "name of the location",
"type": "string"
},
"code": {
"description": "distinct code for the location",
"type": "string"
},
"campusId": {
"description": "ID of the second-level location unit that the third-level unit belongs to",
"type": "string"
},
"metadata": {
"type": "object",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"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}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"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}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"additionalProperties": false,
"required": [
"name",
"campusId",
"code"
]
}
},
"totalRecords": {
"description": "Estimated or exact total number of records",
"type": "integer"
}
},
"required": [
"loclibs",
"totalRecords"
]
}
Example:
{
"loclibs": [
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Main Library",
"code": "ML",
"campusId": "e838c9f0-e559-4872-958f-d9bc97ca1210"
},
{
"id": "0df935eb-f3f4-4741-9ac6-33c500174b96",
"name": "Agriculture Library Reserve",
"code": "ALR",
"campusId": "e838c9f0-e559-4872-958f-d9bc97ca1210"
}
],
"totalRecords": 2
}
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.
Media type: text/plain
Type: any
Example:
unable to list libraries -- malformed parameter 'query', syntax error at column 6
Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to list libraries -- unauthorized
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
Create a new library
POST /location-units/libraries
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "third-level location unit",
"properties": {
"id": {
"type": "string"
},
"name": {
"description": "name of the location",
"type": "string"
},
"code": {
"description": "distinct code for the location",
"type": "string"
},
"campusId": {
"description": "ID of the second-level location unit that the third-level unit belongs to",
"type": "string"
},
"metadata": {
"type": "object",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"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}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"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}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"additionalProperties": false,
"required": [
"name",
"campusId",
"code"
]
}
Example:
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Main Library",
"code": "ML",
"campusId": "e838c9f0-e559-4872-958f-d9bc97ca1210"
}
Returns a newly created item, with server-controlled fields like 'id' populated
URI to the created library item
Media type: application/json
Type: any
Example:
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Main Library",
"code": "ML",
"campusId": "e838c9f0-e559-4872-958f-d9bc97ca1210"
}
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.
Media type: text/plain
Type: any
Example:
"unable to add library -- malformed JSON at 13:3"
Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to create libraries -- unauthorized
Validation errors
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "errors.schema",
"description": "A set of errors",
"type": "object",
"properties": {
"errors": {
"description": "List of errors",
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "error.schema",
"description": "An error",
"properties": {
"message": {
"type": "string",
"description": "Error message text"
},
"type": {
"type": "string",
"description": "Error message type"
},
"code": {
"type": "string",
"description": "Error message code"
},
"parameters": {
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "parameters.schema",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
},
"required": [
"message"
]
}
},
"total_records": {
"description": "Total number of errors",
"type": "integer"
}
}
}
Example:
{
"errors": [
{
"message": "may not be null",
"type": "1",
"code": "-1",
"parameters": [
{
"key": "moduleTo",
"value": "null"
}
]
}
]
}
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
Delete all libraries
DELETE /location-units/libraries
All libraries deleted
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
Retrieve library item with given {libraryId}
GET /location-units/libraries/{id}
Returns item with a given ID
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "third-level location unit",
"properties": {
"id": {
"type": "string"
},
"name": {
"description": "name of the location",
"type": "string"
},
"code": {
"description": "distinct code for the location",
"type": "string"
},
"campusId": {
"description": "ID of the second-level location unit that the third-level unit belongs to",
"type": "string"
},
"metadata": {
"type": "object",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"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}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"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}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"additionalProperties": false,
"required": [
"name",
"campusId",
"code"
]
}
Example:
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Main Library",
"code": "ML",
"campusId": "e838c9f0-e559-4872-958f-d9bc97ca1210"
}
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"library not found"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
Update library item with given {libraryId}
PUT /location-units/libraries/{id}
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "third-level location unit",
"properties": {
"id": {
"type": "string"
},
"name": {
"description": "name of the location",
"type": "string"
},
"code": {
"description": "distinct code for the location",
"type": "string"
},
"campusId": {
"description": "ID of the second-level location unit that the third-level unit belongs to",
"type": "string"
},
"metadata": {
"type": "object",
"readonly": true,
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "metadata.schema",
"title": "Metadata Schema",
"description": "Metadata about creation and changes to records, provided by the server (client should not provide)",
"properties": {
"createdDate": {
"description": "Date and time when the record was created",
"type": "string",
"format": "date-time"
},
"createdByUserId": {
"description": "ID of the user who created the record (when available)",
"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}$"
},
"createdByUsername": {
"description": "Username of the user who created the record (when available)",
"type": "string"
},
"updatedDate": {
"description": "Date and time when the record was last updated",
"type": "string",
"format": "date-time"
},
"updatedByUserId": {
"description": "ID of the user who last updated the record (when available)",
"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}$"
},
"updatedByUsername": {
"description": "Username of the user who last updated the record (when available)",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"createdDate"
]
}
},
"additionalProperties": false,
"required": [
"name",
"campusId",
"code"
]
}
Example:
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Main Library",
"code": "ML",
"campusId": "e838c9f0-e559-4872-958f-d9bc97ca1210"
}
Item successfully updated
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.
Media type: text/plain
Type: any
Example:
"unable to update library -- malformed JSON at 13:4"
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"library not found"
Optimistic locking version conflict
Media type: text/plain
Type: any
Example:
version conflict
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
Delete library item with given {libraryId}
DELETE /location-units/libraries/{id}
Item deleted successfully
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.
Media type: text/plain
Type: any
Example:
"unable to delete library -- constraint violation"
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"library not found"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator