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/institutionsA 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
Skip over a number of elements by specifying an offset value for the query
Example:
0Limit the number of elements returned in the response
Example:
10Requested language. Optional. [lang=en]
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",
"$ref": "locinst.json"
}
},
"totalRecords": {
"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 6Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to list institutions -- unauthorizedInternal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administratorCreate a new institution
POST /location-units/institutionsRequested language. Optional. [lang=en]
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",
"$ref": "raml-util/schemas/metadata.schema",
"readonly": true
}
},
"additionalProperties": false,
"required": [
"name"
]
}
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 -- unauthorizedValidation errors
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"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"
}
]
}
]
}
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administratorDelete all institutions
DELETE /location-units/institutionsRequested language. Optional. [lang=en]
All institutions deleted
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administratorRetrieve institution item with given {institutionId}
GET /location-units/institutions/{id}Requested language. Optional. [lang=en]
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",
"$ref": "raml-util/schemas/metadata.schema",
"readonly": true
}
},
"additionalProperties": false,
"required": [
"name"
]
}
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 administratorUpdate institution item with given {institutionId}
PUT /location-units/institutions/{id}Requested language. Optional. [lang=en]
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",
"$ref": "raml-util/schemas/metadata.schema",
"readonly": true
}
},
"additionalProperties": false,
"required": [
"name"
]
}
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"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administratorDelete institution item with given {institutionId}
DELETE /location-units/institutions/{id}Requested language. Optional. [lang=en]
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 administratorReturn a list of campuses
GET /location-units/campusesA 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
Skip over a number of elements by specifying an offset value for the query
Example:
0Limit the number of elements returned in the response
Example:
10Requested language. Optional. [lang=en]
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",
"$ref": "loccamp.json"
}
},
"totalRecords": {
"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 6Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to list campuses -- unauthorizedInternal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administratorCreate a new campus
POST /location-units/campusesRequested language. Optional. [lang=en]
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",
"$ref": "raml-util/schemas/metadata.schema",
"readonly": true
}
},
"additionalProperties": false,
"required": [
"name", "institutionId"
]
}
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 -- unauthorizedValidation errors
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"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"
}
]
}
]
}
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administratorDelete all campuses
DELETE /location-units/campusesRequested language. Optional. [lang=en]
All campuses deleted
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administratorRetrieve campus item with given {campusId}
GET /location-units/campuses/{id}Requested language. Optional. [lang=en]
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",
"$ref": "raml-util/schemas/metadata.schema",
"readonly": true
}
},
"additionalProperties": false,
"required": [
"name", "institutionId"
]
}
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 administratorUpdate campus item with given {campusId}
PUT /location-units/campuses/{id}Requested language. Optional. [lang=en]
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",
"$ref": "raml-util/schemas/metadata.schema",
"readonly": true
}
},
"additionalProperties": false,
"required": [
"name", "institutionId"
]
}
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"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administratorDelete campus item with given {campusId}
DELETE /location-units/campuses/{id}Requested language. Optional. [lang=en]
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 administratorReturn a list of libraries
GET /location-units/librariesA 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
Skip over a number of elements by specifying an offset value for the query
Example:
0Limit the number of elements returned in the response
Example:
10Requested language. Optional. [lang=en]
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",
"$ref": "loclib.json"
}
},
"totalRecords": {
"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 6Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to list libraries -- unauthorizedInternal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administratorCreate a new library
POST /location-units/librariesRequested language. Optional. [lang=en]
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",
"$ref": "raml-util/schemas/metadata.schema",
"readonly": true
}
},
"additionalProperties": false,
"required": [
"name", "campusId"
]
}
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 -- unauthorizedValidation errors
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"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"
}
]
}
]
}
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administratorDelete all libraries
DELETE /location-units/librariesRequested language. Optional. [lang=en]
All libraries deleted
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
Internal server error, contact administratorRetrieve library item with given {libraryId}
GET /location-units/libraries/{id}Requested language. Optional. [lang=en]
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",
"$ref": "raml-util/schemas/metadata.schema",
"readonly": true
}
},
"additionalProperties": false,
"required": [
"name", "campusId"
]
}
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 administratorUpdate library item with given {libraryId}
PUT /location-units/libraries/{id}Requested language. Optional. [lang=en]
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",
"$ref": "raml-util/schemas/metadata.schema",
"readonly": true
}
},
"additionalProperties": false,
"required": [
"name", "campusId"
]
}
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"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administratorDelete library item with given {libraryId}
DELETE /location-units/libraries/{id}Requested language. Optional. [lang=en]
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