Codex API (v1)

https://github.com/folio-org/mod-codex-ekb

Table of contents

Codex API

This documents the FOLIO codex API

Codex instances

Codex instance collection

GET /codex-instances

Retrieve codex-instance item with given {codex-instanceId}

GET /codex-instances
Query Parameters
  • query: (string)

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

    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
    
  • offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)

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

    Example:

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

    Limit the number of elements returned in the response

    Example:

    10
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns item with a given ID

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "additionalProperties": false,
  "description": "Collection of instances",
  "properties": {
    "instances": {
      "type": "array",
      "description": "Collection of instances",
      "items": {
        "type": "object",
        "$ref": "instance.json"
      }
    },
    "resultInfo": {
      "$ref": "../resultInfo.schema"
    }
  },
  "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"
      }
    ]
  }
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

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

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

"unable to list codex-instances -- unauthorized"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"codex-instance not found"

Response 422

Validation errors

Body

Media type: application/json

Type: json

Content:

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

Example:

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

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

GET /codex-instances/{id}

Retrieve codex-instance item with given {codex-instanceId}

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

    Requested language. Optional. [lang=en]

Response 200

Returns item with a given ID

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "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"
}

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to get retrieve codex-instance -- unauthorized

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"codex-instance not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator