Codex Packages API (v1)

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

Table of contents

Codex Packages API

This documents the FOLIO codex packages API

Codex packages

Codex packages collection

GET /codex-packages

Retrieve codex-package item with given {codex-packageId}

GET /codex-packages
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 name = academic

    Example:

    (username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
    
    name=academic
    
  • 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 packages",
  "properties": {
    "packages": {
      "type": "array",
      "description": "Collection of packages",
      "items": {
        "type": "object",
        "$ref": "package.json"
      }
    },
    "resultInfo": {
      "description": "Result information schema",
      "$ref": "../resultInfo.schema"
    }
  },
  "required": [
    "packages",
    "resultInfo"
  ]
}

Example:

{
  "instances": [
    {
      "id": "18-134",
      "identifier": "",
      "name": "Academic ASAP",
      "description": "",
      "type": "Aggregated Full Text",
      "providerId": "18",
      "provider": "Gale|Cengage",
      "platform": "",
      "itemCount": 100,
      "coverage":{"beginCoverage":"2018-08-13","endCoverage":"2018-09-13"},
      "isSelected": "Yes",
      "source": "ekb",
      "lastModified": "2019-02-11"
    },
    {
      "id": "bfcefc83-4a2f-44f0-ac1f-ba2424cea48a",
      "identifier": "",
      "name": "Academic OneFile",
      "description": "Academic OneFile description",
      "type": "Online Reference",
      "providerId": "bfcefc83-4a2f-44f0-ac1f-ba2424cea48b",
      "provider": "Gale|Cengage",
      "platform": "Gale|Cengage platform",
      "itemCount": 100,
      "coverage":{"beginCoverage":"2018-08-13","endCoverage":"2018-09-13"},
      "isSelected": "NotSpecified",
      "source": "localkb",
      "lastModified": "2019-02-11"
    }
  ],
  "resultInfo" : {
    "totalRecords" : 2,
    "facets" : [ ],
    "diagnostics" : [ {
      "source" : "mod-agreements-1.0.2",
      "code" : "200",
      "recordCount" : 1,
      "query" : "(name = a) sortby name"
    }, {
      "source" : "mod-codex-ekb-1.1.0",
      "code" : "200",
      "recordCount" : 1,
      "query" : "(name = a) sortby name"
    }
  }
}

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-packages -- 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-packages -- unauthorized"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"codex-package 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": {
      "description": "Total number of errors",
      "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-packages/{id}

Retrieve codex-package item with given {codex-packageId}

GET /codex-packages/{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 Package Schema",
  "description": "Codex Package Schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "The internal ID of the Package record as known by the source, unique and can have different formats"
    },
    "identifier": {
      "type": "string",
      "description": "An external identifier used to track the Package (e.g. a barcode)"
    },
    "name": {
      "type": "string",
      "description": "A name (or label) associated with the Package"
    },
    "description": {
      "type": "string",
      "description": "A free-form description of the Package"
    },
    "type": {
      "type": "string",
      "description": "The type of package - what sort of collection does it represent. (e.g. DVD box set; boundwidth; archival cardboard box; etc..)",
      "$ref" : "packageType.json"
    },
    "providerId": {
      "type": "string",
      "description": "Link to provider object associated with this resource (could be in another domain)"
    },
    "provider": {
      "type": "string",
      "description": "Name of provider for display purposes"
    },
    "platform": {
      "type": "string",
      "description": "Platform hosting the e-resource"
    },
    "itemCount": {
      "type": "integer",
      "description": "Number of items in the package"
    },
    "coverage": {
      "type": "object",
      "description": "Coverage date for the package itself, rather than its contents",
      "$ref" : "coverage.json"
    },
    "isSelected": {
      "type": "object",
      "description": "Selection state (`is it held?`) of the package itself, rather than its contents. Mostly relevant for e-resources",
      "$ref" : "selectionStatus.json"
    },
    "source": {
      "type": "string",
      "description": "a label indicating the source of the package, e.g. kb, local"
    },
    "lastModified": {
      "type": "string",
      "description": "date when this package was last modified"
    }
  },
  "required": [
    "id",
    "name"
  ]
}

Example:

{
  "id": "bfcefc83-4a2f-44f0-ac1f-ba2424cea48a",
  "identifier": "",
  "name": "Academic OneFile",
  "description": "Academic OneFile description",
  "type": "Online Reference",
  "providerId": "18",
  "provider": "Gale|Cengage",
  "platform": "Gale|Cengage platform",
  "itemCount": 100,
  "coverage":{"beginCoverage":"2018-08-13","endCoverage":"2018-09-13"},
  "source": "localkb",
  "isSelected": "NotSpecified",
  "lastModified": "2019-02-11"
}

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to get retrieve codex-package -- unauthorized

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"codex-package 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

Codex packages sources

Codex packages sources

Codex sources

GET a list of source modules that implement codex-packages interface

GET /codex-packages-sources
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns a list of codex-packages-source items

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "additionalProperties": false,
  "description": "Collection of sources",
  "properties": {
    "sources": {
      "type": "array",
      "description": "Collection of sources",
      "items": {
        "type": "object",
        "$ref": "source.json"
      }
    }
  },
  "required": [
    "sources"
  ]
}

Example:

{
  "source": [
    {
      "id": "ekb",
      "name": "mod-codex-ekb-1.1.0"
    },
    {
      "id": "localekb",
      "name": "mod-agreements-1.0.2"
    }
  ]
}

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-packages-sources -- malformed parameter 'query', syntax error at column 6

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator