http://github.com/org/folio/mod-inventory-storage
This documents the API calls that can be made to query and manage (shelf) locations of the system
Collection of location items.
Return a list of locations
GET /locations
Whether to include shadow locations in the response or not.
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 location items
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "List of (shelf) locations.",
"type": "object",
"properties": {
"locations": {
"id": "locations",
"description": "List of (shelf) locations.",
"type": "array",
"items": {
"type": "object",
"$ref": "location.json"
}
},
"totalRecords": {
"description": "Estimated or exact total number of records",
"type": "integer"
}
},
"required": [
"locations",
"totalRecords"
]
}
Example:
{
"locations": [
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Miller General Stacks",
"code": "UA/CB/LC/GS",
"isActive": true,
"institutionId": "4b2a3d97-01c3-4ef3-98a5-ae4e853429b4",
"campusId": "b595d838-b1d5-409e-86ac-af3b41bde0be",
"libraryId": "e2889f93-92f2-4937-b944-5452a575367e",
"details": {
"a": "b",
"foo": "bar"
},
"primaryServicePoint": "79faacf1-4ba4-42c7-8b2a-566b259e4641",
"servicePointIds": [
"79faacf1-4ba4-42c7-8b2a-566b259e4641"
]
},
{
"id": "97ee6cd9-17ef-47f8-acbb-ec16fb2cb98d",
"name": "Special Reading Room",
"code": "UX/BB/LC/RR",
"isActive": true,
"institutionId": "4b2a3d97-01c3-4ef3-98a5-ae4e853429b4",
"campusId": "b595d838-b1d5-409e-86ac-af3b41bde0be",
"libraryId": "a23d1dbc-e7ba-4c00-baf4-9770bdfb87c6",
"details": {
"foo": "gryf"
},
"primaryServicePoint": "79faacf1-4ba4-42c7-8b2a-566b259e4641",
"servicePointIds": [
"79faacf1-4ba4-42c7-8b2a-566b259e4641"
]
}
],
"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 locations -- malformed parameter 'query', syntax error at column 6
Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to list locations -- unauthorized
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
Create a new location
POST /locations
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A (shelf) location, the forth-level location unit below institution, campus, and library.",
"javaType": "org.folio.rest.jaxrs.model.Location",
"type": "object",
"properties": {
"id": {
"description": "id of this (shelf) location record as UUID.",
"type": "string"
},
"name": {
"description": "Name of the (shelf) location",
"type": "string"
},
"code": {
"description": "Code of the (shelf) location, usually an abbreviation of the name.",
"type": "string"
},
"description": {
"description": "Description of the (shelf) location.",
"type": "string"
},
"discoveryDisplayName": {
"description": "Name of the (shelf) location to be shown in the discovery.",
"type": "string"
},
"isActive": {
"description": "Whether this (shelf) location is active. Inactive (shelf) locations can no longer been used.",
"type": "boolean"
},
"institutionId": {
"description": "The UUID of the institution, the first-level location unit, this (shelf) location belongs to.",
"type": "string"
},
"institution": {
"description": "The institution, the first-level location unit, this (shelf) location belongs to.",
"type": "object",
"$ref": "locinst.json",
"readonly": true,
"folio:isVirtual": true,
"folio:linkBase": "location-units/institutions",
"folio:linkFromField": "institutionId",
"folio:linkToField": "id",
"folio:includedElement": "locinsts.0"
},
"campusId": {
"description": "The UUID of the campus, the second-level location unit, this (shelf) location belongs to.",
"type": "string"
},
"campus": {
"description": "The campus, the second-level location unit, this (shelf) location belongs to",
"type": "object",
"$ref": "loccamp.json",
"readonly": true,
"folio:isVirtual": true,
"folio:linkBase": "location-units/campuses",
"folio:linkFromField": "campusId",
"folio:linkToField": "id",
"folio:includedElement": "loccamps.0"
},
"libraryId": {
"description": "The UUID of the library, the third-level location unit, this (shelf) location belongs to.",
"type": "string"
},
"library": {
"description": "The library, the third-level location unit, this (shelf) location belongs to.",
"type": "object",
"$ref": "locinst.json",
"readonly": true,
"folio:isVirtual": true,
"folio:linkBase": "location-units/libraries",
"folio:linkFromField": "libraryId",
"folio:linkToField": "id",
"folio:includedElement": "loclibs.0"
},
"details": {
"description": "Details about this (shelf) location.",
"type": "object"
},
"primaryServicePoint": {
"description": "The UUID of the primary service point of this (shelf) location.",
"format": "uuid",
"type": "string"
},
"primaryServicePointObject": {
"type": "object",
"description": "Dereferenced object for primary service point. This should really just be called 'primaryServicePoint', but the field containing the ID of this object has that name -- it should really be called 'primaryServicePointId' -- so we need something different for this one.",
"$ref": "../servicepoint.json",
"readonly": true,
"folio:isVirtual": true,
"folio:linkBase": "service-points",
"folio:linkFromField": "primaryServicePoint",
"folio:linkToField": "id",
"folio:includedElement": "servicepoints.0"
},
"servicePointIds": {
"description": "All service points that this (shelf) location has.",
"type": "array",
"items": {
"description": "The UUID of a service point that belongs to this (shelf) location.",
"type": "string",
"format": "uuid",
"not": {
"type": "null"
}
}
},
"isFloatingCollection": {
"description": "Items checked in/out from this location can be checked in/out to other locations with the same flag.",
"type": "boolean"
},
"servicePoints": {
"type": "array",
"description": "List of dereferenced service points",
"items": {
"type": "object",
"$ref": "../servicepoint.json"
},
"readonly": true,
"folio:isVirtual": true,
"folio:linkBase": "service-points",
"folio:linkFromField": "servicePointIds",
"folio:linkToField": "id",
"folio:includedElement": "servicepoints"
},
"isShadow": {
"description": "Whether this location is a shadow location. Shadow locations are used to represent virtual locations that no items are assignable to them. They only relate to external libraries and virtual items.",
"type": "boolean",
"default": false
},
"metadata": {
"type": "object",
"$ref": "../raml-util/schemas/metadata.schema",
"readonly": true
}
},
"additionalProperties": false,
"required": [
"name",
"code",
"institutionId",
"campusId",
"libraryId",
"primaryServicePoint"
]
}
Example:
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Miller General Stacks",
"code": "UA/CB/LC/GS",
"isActive": true,
"description": "The very general stacks of Miller",
"discoveryDisplayName": "Miller General",
"institutionId": "4b2a3d97-01c3-4ef3-98a5-ae4e853429b4",
"campusId": "b595d838-b1d5-409e-86ac-af3b41bde0be",
"libraryId": "e2889f93-92f2-4937-b944-5452a575367e",
"details": {
"a": "b",
"foo": "bar"
},
"primaryServicePoint": "79faacf1-4ba4-42c7-8b2a-566b259e4641",
"servicePointIds": [
"79faacf1-4ba4-42c7-8b2a-566b259e4641"
]
}
Returns a newly created item, with server-controlled fields like 'id' populated
URI to the created location item
Media type: application/json
Type: any
Example:
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Miller General Stacks",
"code": "UA/CB/LC/GS",
"isActive": true,
"description": "The very general stacks of Miller",
"discoveryDisplayName": "Miller General",
"institutionId": "4b2a3d97-01c3-4ef3-98a5-ae4e853429b4",
"campusId": "b595d838-b1d5-409e-86ac-af3b41bde0be",
"libraryId": "e2889f93-92f2-4937-b944-5452a575367e",
"details": {
"a": "b",
"foo": "bar"
},
"primaryServicePoint": "79faacf1-4ba4-42c7-8b2a-566b259e4641",
"servicePointIds": [
"79faacf1-4ba4-42c7-8b2a-566b259e4641"
]
}
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 location -- malformed JSON at 13:3"
Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to create locations -- 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 locations
DELETE /locations
All locations deleted
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator
Retrieve location item with given {locationId}
GET /locations/{id}
Returns item with a given ID
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A (shelf) location, the forth-level location unit below institution, campus, and library.",
"javaType": "org.folio.rest.jaxrs.model.Location",
"type": "object",
"properties": {
"id": {
"description": "id of this (shelf) location record as UUID.",
"type": "string"
},
"name": {
"description": "Name of the (shelf) location",
"type": "string"
},
"code": {
"description": "Code of the (shelf) location, usually an abbreviation of the name.",
"type": "string"
},
"description": {
"description": "Description of the (shelf) location.",
"type": "string"
},
"discoveryDisplayName": {
"description": "Name of the (shelf) location to be shown in the discovery.",
"type": "string"
},
"isActive": {
"description": "Whether this (shelf) location is active. Inactive (shelf) locations can no longer been used.",
"type": "boolean"
},
"institutionId": {
"description": "The UUID of the institution, the first-level location unit, this (shelf) location belongs to.",
"type": "string"
},
"institution": {
"description": "The institution, the first-level location unit, this (shelf) location belongs to.",
"type": "object",
"$ref": "locinst.json",
"readonly": true,
"folio:isVirtual": true,
"folio:linkBase": "location-units/institutions",
"folio:linkFromField": "institutionId",
"folio:linkToField": "id",
"folio:includedElement": "locinsts.0"
},
"campusId": {
"description": "The UUID of the campus, the second-level location unit, this (shelf) location belongs to.",
"type": "string"
},
"campus": {
"description": "The campus, the second-level location unit, this (shelf) location belongs to",
"type": "object",
"$ref": "loccamp.json",
"readonly": true,
"folio:isVirtual": true,
"folio:linkBase": "location-units/campuses",
"folio:linkFromField": "campusId",
"folio:linkToField": "id",
"folio:includedElement": "loccamps.0"
},
"libraryId": {
"description": "The UUID of the library, the third-level location unit, this (shelf) location belongs to.",
"type": "string"
},
"library": {
"description": "The library, the third-level location unit, this (shelf) location belongs to.",
"type": "object",
"$ref": "locinst.json",
"readonly": true,
"folio:isVirtual": true,
"folio:linkBase": "location-units/libraries",
"folio:linkFromField": "libraryId",
"folio:linkToField": "id",
"folio:includedElement": "loclibs.0"
},
"details": {
"description": "Details about this (shelf) location.",
"type": "object"
},
"primaryServicePoint": {
"description": "The UUID of the primary service point of this (shelf) location.",
"format": "uuid",
"type": "string"
},
"primaryServicePointObject": {
"type": "object",
"description": "Dereferenced object for primary service point. This should really just be called 'primaryServicePoint', but the field containing the ID of this object has that name -- it should really be called 'primaryServicePointId' -- so we need something different for this one.",
"$ref": "../servicepoint.json",
"readonly": true,
"folio:isVirtual": true,
"folio:linkBase": "service-points",
"folio:linkFromField": "primaryServicePoint",
"folio:linkToField": "id",
"folio:includedElement": "servicepoints.0"
},
"servicePointIds": {
"description": "All service points that this (shelf) location has.",
"type": "array",
"items": {
"description": "The UUID of a service point that belongs to this (shelf) location.",
"type": "string",
"format": "uuid",
"not": {
"type": "null"
}
}
},
"isFloatingCollection": {
"description": "Items checked in/out from this location can be checked in/out to other locations with the same flag.",
"type": "boolean"
},
"servicePoints": {
"type": "array",
"description": "List of dereferenced service points",
"items": {
"type": "object",
"$ref": "../servicepoint.json"
},
"readonly": true,
"folio:isVirtual": true,
"folio:linkBase": "service-points",
"folio:linkFromField": "servicePointIds",
"folio:linkToField": "id",
"folio:includedElement": "servicepoints"
},
"isShadow": {
"description": "Whether this location is a shadow location. Shadow locations are used to represent virtual locations that no items are assignable to them. They only relate to external libraries and virtual items.",
"type": "boolean",
"default": false
},
"metadata": {
"type": "object",
"$ref": "../raml-util/schemas/metadata.schema",
"readonly": true
}
},
"additionalProperties": false,
"required": [
"name",
"code",
"institutionId",
"campusId",
"libraryId",
"primaryServicePoint"
]
}
Example:
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Miller General Stacks",
"code": "UA/CB/LC/GS",
"isActive": true,
"description": "The very general stacks of Miller",
"discoveryDisplayName": "Miller General",
"institutionId": "4b2a3d97-01c3-4ef3-98a5-ae4e853429b4",
"campusId": "b595d838-b1d5-409e-86ac-af3b41bde0be",
"libraryId": "e2889f93-92f2-4937-b944-5452a575367e",
"details": {
"a": "b",
"foo": "bar"
},
"primaryServicePoint": "79faacf1-4ba4-42c7-8b2a-566b259e4641",
"servicePointIds": [
"79faacf1-4ba4-42c7-8b2a-566b259e4641"
]
}
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"location not found"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administrator
Update a location by id
PUT /locations/{id}
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A (shelf) location, the forth-level location unit below institution, campus, and library.",
"javaType": "org.folio.rest.jaxrs.model.Location",
"type": "object",
"properties": {
"id": {
"description": "id of this (shelf) location record as UUID.",
"type": "string"
},
"name": {
"description": "Name of the (shelf) location",
"type": "string"
},
"code": {
"description": "Code of the (shelf) location, usually an abbreviation of the name.",
"type": "string"
},
"description": {
"description": "Description of the (shelf) location.",
"type": "string"
},
"discoveryDisplayName": {
"description": "Name of the (shelf) location to be shown in the discovery.",
"type": "string"
},
"isActive": {
"description": "Whether this (shelf) location is active. Inactive (shelf) locations can no longer been used.",
"type": "boolean"
},
"institutionId": {
"description": "The UUID of the institution, the first-level location unit, this (shelf) location belongs to.",
"type": "string"
},
"institution": {
"description": "The institution, the first-level location unit, this (shelf) location belongs to.",
"type": "object",
"$ref": "locinst.json",
"readonly": true,
"folio:isVirtual": true,
"folio:linkBase": "location-units/institutions",
"folio:linkFromField": "institutionId",
"folio:linkToField": "id",
"folio:includedElement": "locinsts.0"
},
"campusId": {
"description": "The UUID of the campus, the second-level location unit, this (shelf) location belongs to.",
"type": "string"
},
"campus": {
"description": "The campus, the second-level location unit, this (shelf) location belongs to",
"type": "object",
"$ref": "loccamp.json",
"readonly": true,
"folio:isVirtual": true,
"folio:linkBase": "location-units/campuses",
"folio:linkFromField": "campusId",
"folio:linkToField": "id",
"folio:includedElement": "loccamps.0"
},
"libraryId": {
"description": "The UUID of the library, the third-level location unit, this (shelf) location belongs to.",
"type": "string"
},
"library": {
"description": "The library, the third-level location unit, this (shelf) location belongs to.",
"type": "object",
"$ref": "locinst.json",
"readonly": true,
"folio:isVirtual": true,
"folio:linkBase": "location-units/libraries",
"folio:linkFromField": "libraryId",
"folio:linkToField": "id",
"folio:includedElement": "loclibs.0"
},
"details": {
"description": "Details about this (shelf) location.",
"type": "object"
},
"primaryServicePoint": {
"description": "The UUID of the primary service point of this (shelf) location.",
"format": "uuid",
"type": "string"
},
"primaryServicePointObject": {
"type": "object",
"description": "Dereferenced object for primary service point. This should really just be called 'primaryServicePoint', but the field containing the ID of this object has that name -- it should really be called 'primaryServicePointId' -- so we need something different for this one.",
"$ref": "../servicepoint.json",
"readonly": true,
"folio:isVirtual": true,
"folio:linkBase": "service-points",
"folio:linkFromField": "primaryServicePoint",
"folio:linkToField": "id",
"folio:includedElement": "servicepoints.0"
},
"servicePointIds": {
"description": "All service points that this (shelf) location has.",
"type": "array",
"items": {
"description": "The UUID of a service point that belongs to this (shelf) location.",
"type": "string",
"format": "uuid",
"not": {
"type": "null"
}
}
},
"isFloatingCollection": {
"description": "Items checked in/out from this location can be checked in/out to other locations with the same flag.",
"type": "boolean"
},
"servicePoints": {
"type": "array",
"description": "List of dereferenced service points",
"items": {
"type": "object",
"$ref": "../servicepoint.json"
},
"readonly": true,
"folio:isVirtual": true,
"folio:linkBase": "service-points",
"folio:linkFromField": "servicePointIds",
"folio:linkToField": "id",
"folio:includedElement": "servicepoints"
},
"isShadow": {
"description": "Whether this location is a shadow location. Shadow locations are used to represent virtual locations that no items are assignable to them. They only relate to external libraries and virtual items.",
"type": "boolean",
"default": false
},
"metadata": {
"type": "object",
"$ref": "../raml-util/schemas/metadata.schema",
"readonly": true
}
},
"additionalProperties": false,
"required": [
"name",
"code",
"institutionId",
"campusId",
"libraryId",
"primaryServicePoint"
]
}
Example:
{
"id": "d9cd0bed-1b49-4b5e-a7bd-064b8d177231",
"name": "Miller General Stacks",
"code": "UA/CB/LC/GS",
"isActive": true,
"description": "The very general stacks of Miller",
"discoveryDisplayName": "Miller General",
"institutionId": "4b2a3d97-01c3-4ef3-98a5-ae4e853429b4",
"campusId": "b595d838-b1d5-409e-86ac-af3b41bde0be",
"libraryId": "e2889f93-92f2-4937-b944-5452a575367e",
"details": {
"a": "b",
"foo": "bar"
},
"primaryServicePoint": "79faacf1-4ba4-42c7-8b2a-566b259e4641",
"servicePointIds": [
"79faacf1-4ba4-42c7-8b2a-566b259e4641"
]
}
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 location -- malformed JSON at 13:4"
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"location not found"
Optimistic locking version conflict
Media type: text/plain
Type: any
Example:
version conflict
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 location item with given {locationId}
DELETE /locations/{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 location -- constraint violation"
Item with a given ID not found
Media type: text/plain
Type: any
Example:
"location not found"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administrator