https://github.com/folio-org/mod-codex-ekb
This documents the FOLIO codex API
Codex instance collection
Retrieve a list of codex-instance items.
GET /codex-instancesA 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: for example title = earth
Example:
(username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
title=earth
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 codex-instance items
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"additionalProperties": false,
"description": "Collection of instances",
"properties": {
"instances": {
"type": "array",
"description": "Collection of instances",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Codex Instance Schema",
"description": "Codex Instance Schema",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "the ID of the original record within its own database: since these come from various sources they may take different forms, e.g. integer, UUID"
},
"title": {
"type": "string",
"description": "the primary title (or label) associated with the resource"
},
"altTitle": {
"type": "string",
"description": "an alternative title for the resource. (e.g. original language version title of a movie)"
},
"series": {
"type": "string",
"description": "a series title associated with the resource (e.g. Harry Potter)"
},
"contributor": {
"type": "array",
"description": "list of contributors to the resource",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"description": "type of contributor to the resource"
},
"name": {
"type": "string",
"description": "name of contributor to the resource"
}
}
},
"additionalItems": true,
"uniqueItems": true
},
"subject": {
"type": "array",
"description": "list of subjects this resource belongs to",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"description": "type of subject"
},
"name": {
"type": "string",
"description": "name of subject"
}
}
},
"additionalItems": true,
"uniqueItems": true
},
"publisher": {
"type": "string",
"description": "name of publisher of the resource"
},
"date": {
"type": "string",
"description": "the date of publication of the resource"
},
"type": {
"type": "string",
"description": "content type of the resource",
"enum": [
"audio",
"audiobooks",
"books",
"bookseries",
"databases",
"ebooks",
"kits",
"maps",
"music",
"newspapers",
"newsletters",
"periodicals",
"posters",
"reports",
"proceedings",
"thesisanddissertation",
"unspecified",
"video",
"webresources"
]
},
"format": {
"type": "string",
"description": "format of the resource"
},
"identifier": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"value": {
"type": "string",
"description": "identifier type : e.g. ISSN"
},
"type": {
"type": "string",
"description": "identifier value"
}
}
},
"additionalItems": true,
"uniqueItems": true,
"description": "an extensible set of name-value pairs of identifiers associated with the resource"
},
"source": {
"type": "string",
"description": "a label indicating the source of the recent, e.g. kb, local"
},
"language": {
"type": "array",
"description": "the set of languages used by the resource",
"items": {
"type": "string"
}
},
"rights": {
"type": "string",
"description": "access rights associated with the resource"
},
"version": {
"type": "string",
"description": "version of the resource"
},
"lastModified": {
"type": "string",
"description": "date/time when this resource was last modified"
}
},
"required": [
"id",
"title",
"type",
"source"
]
}
},
"resultInfo": {
"description": "Result information schema",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"totalRecords": {
"type": "integer",
"description": "Estimated or exact total number of records"
},
"totalRecordsEstimated": {
"type": "boolean",
"description": "True if totalRecords is an estimation, false if it is the exact number"
},
"totalRecordsRounded": {
"type": "integer",
"description": "The rounded value of totalRecords if totalRecords is an estimation"
},
"responseTime": {
"type": "number",
"description": "Response time"
},
"facets": {
"type": "array",
"description": "Array of facets",
"items": {
"type": "object",
"description": "A facet",
"properties": {
"facetValues": {
"type": "array",
"description": "Array of facet values",
"items": {
"type": "object",
"description": "A facet value",
"properties": {
"count": {
"type": "integer",
"description": "Count of facet values"
},
"value": {
"description": "Value Object"
}
}
},
"additionalProperties": false
},
"type": {
"type": "string",
"description": "Type of facet"
}
},
"additionalProperties": false
}
},
"diagnostics": {
"type": "array",
"description": "Array of diagnostic information",
"items": {
"type": "object",
"description": "Diagnostic information",
"properties": {
"source": {
"type": "string",
"description": "Source reporting the diagnostic information"
},
"code": {
"type": "string",
"description": "Diagnostic Code"
},
"message": {
"type": "string",
"description": "Diagnostic Message"
},
"module": {
"type": "string",
"description": "Module reporting diagnostic information"
},
"recordCount": {
"type": "integer",
"description": "Record Count for diagnostics"
},
"query": {
"type": "string",
"description": "CQL Query associated with results"
}
}
}
}
},
"additionalProperties": false
}
},
"required": [
"instances",
"resultInfo"
]
}Example:
{
"instances": [
{
"id": "1",
"title": "first instance",
"altTitle": "first alternative title",
"series": "first series",
"contributor": [],
"publisher": "first publisher",
"date": "first date",
"type": "newsletters",
"format": "first format",
"identifier": [
{
"type": "first_id_type",
"value": "first_id_value"
}
],
"source": "first source",
"language": [
"english",
"french"
],
"rights": "first rights",
"version": "first version",
"lastModified": "first lastModified"
},
{
"id": "2",
"title": "second instance",
"altTitle": "second alternative title",
"series": "second series",
"contributor": [],
"publisher": "second publisher",
"date": "second date",
"type": "reports",
"format": "second format",
"identifier": [
{
"type": "second_id_type",
"value": "second_id_value"
}
],
"source": "second source",
"language": [
"english",
"french"
],
"rights": "second rights",
"version": "second version",
"lastModified": "second lastModified"
}
],
"resultInfo": {
"totalRecords": 2,
"responseTime": 8.9,
"facets": [
{
"facetValues": [
{
"count": 15,
"value": "Handey1"
},
{
"count": 10,
"value": "Handey"
}
],
"type": "lastName"
},
{
"facetValues": [
{
"count": 18,
"value": "true"
},
{
"count": 7,
"value": "false"
}
],
"type": "active"
}
],
"diagnostics": [
{
"source": "mock1",
"code": "200"
},
{
"source": "mock2",
"code": "400",
"message": "unsupported index foo.bar"
}
]
}
}
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 codex-instances -- malformed parameter 'query', syntax error at column 6Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
"unable to list instances -- unauthorized"
Validation errors
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",
"$schema": "http://json-schema.org/draft-04/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": {
"type": "object",
"description": "Error message parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"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 administratorRetrieve codex-instance item with given {codex-instanceId}
GET /codex-instances/{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#",
"title": "Codex Instance Schema",
"description": "Codex Instance Schema",
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "the ID of the original record within its own database: since these come from various sources they may take different forms, e.g. integer, UUID"
},
"title": {
"type": "string",
"description": "the primary title (or label) associated with the resource"
},
"altTitle": {
"type": "string",
"description": "an alternative title for the resource. (e.g. original language version title of a movie)"
},
"series": {
"type": "string",
"description": "a series title associated with the resource (e.g. Harry Potter)"
},
"contributor": {
"type": "array",
"description": "list of contributors to the resource",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"description": "type of contributor to the resource"
},
"name": {
"type": "string",
"description": "name of contributor to the resource"
}
}
},
"additionalItems": true,
"uniqueItems": true
},
"subject": {
"type": "array",
"description": "list of subjects this resource belongs to",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"description": "type of subject"
},
"name": {
"type": "string",
"description": "name of subject"
}
}
},
"additionalItems": true,
"uniqueItems": true
},
"publisher": {
"type": "string",
"description": "name of publisher of the resource"
},
"date": {
"type": "string",
"description": "the date of publication of the resource"
},
"type": {
"type": "string",
"description": "content type of the resource",
"enum": [
"audio",
"audiobooks",
"books",
"bookseries",
"databases",
"ebooks",
"kits",
"maps",
"music",
"newspapers",
"newsletters",
"periodicals",
"posters",
"reports",
"proceedings",
"thesisanddissertation",
"unspecified",
"video",
"webresources"
]
},
"format": {
"type": "string",
"description": "format of the resource"
},
"identifier": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"value": {
"type": "string",
"description": "identifier type : e.g. ISSN"
},
"type": {
"type": "string",
"description": "identifier value"
}
}
},
"additionalItems": true,
"uniqueItems": true,
"description": "an extensible set of name-value pairs of identifiers associated with the resource"
},
"source": {
"type": "string",
"description": "a label indicating the source of the recent, e.g. kb, local"
},
"language": {
"type": "array",
"description": "the set of languages used by the resource",
"items": {
"type": "string"
}
},
"rights": {
"type": "string",
"description": "access rights associated with the resource"
},
"version": {
"type": "string",
"description": "version of the resource"
},
"lastModified": {
"type": "string",
"description": "date/time when this resource was last modified"
}
},
"required": [
"id",
"title",
"type",
"source"
]
}Example:
{
"id": "1",
"title": "first instance",
"altTitle": "first alternative title",
"series": "first series",
"contributor": [],
"publisher": "first publisher",
"date": "first date",
"type": "newsletters",
"format": "first format",
"identifier": [
{
"type": "first_id_type",
"value": "first_id_value"
}
],
"source": "first source",
"language": [
"english",
"french"
],
"rights": "first rights",
"version": "first version",
"lastModified": "first lastModified"
}
Not authorized to perform requested action
Media type: text/plain
Type: any
Example:
unable to get retrieve codex-instance -- unauthorizedItem with a given ID not found
Media type: text/plain
Type: any
Example:
"codex-instance not found"
Internal server error, e.g. due to misconfiguration
Media type: text/plain
Type: any
Example:
internal server error, contact administrator