Real Time Availability Check (v1.0)

https://github.com/folio-org/mod-rtac

Table of contents

Real Time Availability Checker Integration

This module allows 3rd party discovery services to check for FOLIO inventory availability

RTAC Batch API

Batch API to get instances with items and holdings from inventory. The expectation is that the mode of issuance "serial" and nature of content "journal" and "newspaper" are present in the target system. The module uses these values to qualify an instance as a periodical.

POST /rtac-batch

Retrieve holding information from inventory in a batch

POST /rtac-batch
Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Define format of request data with instances ids",
  "type": "object",
  "properties": {
    "instanceIds": {
      "description": "Inventory instances identifiers",
      "type": "array",
      "items": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "description": "A universally unique identifier (UUID), this is a 128-bit number used to identify a record and is shown in hex with dashes, for example 6312d172-f0cf-40f6-b27d-9fa8feaf332f; the UUID version must be from 1-5; see https://dev.folio.org/guides/uuids/",
        "type": "string",
        "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
      }
    },
    "fullPeriodicals": {
      "description": "if set to true, then item-level information is added to all periodicals without holdings-level information",
      "type": "boolean",
      "default": false
    }
  },
  "additionalProperties": false,
  "required": [
    "instanceIds"
  ]
}

Example:

{
  "instanceIds": [
    "5bf370e0-8cca-4d9c-82e4-5170ab2a0a39",
    "7212ba6a-8dcf-45a1-be9a-ffaa847c4423",
    "100d10bf-2f06-4aa0-be15-0b95b2d9f9e3",
    "0aaef1ea-69eb-4f6e-a077-cea159317ce3",
    "1b74ab75-9f41-4837-8662-a1d99118008d"
  ],
  "fullPeriodicals" : false
}

Response 200

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Batch holdings response",
  "properties": {
    "holdings": {
      "description": "Real Time Availability Check (RTAC) holding details",
      "type": "array",
      "id": "holdingsList",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "additionalProperties": false,
        "description": "Collection of holdings",
        "javaType": "org.folio.rest.jaxrs.model.RtacHoldings",
        "properties": {
          "instanceId": {
            "description": "The FOLIO instance identifier",
            "type": "string",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
          },
          "holdings": {
            "description": "Collection of holdings",
            "type": "array",
            "items": {
              "type": "object",
              "$schema": "http://json-schema.org/draft-04/schema#",
              "title": "RTAC Holding Schema",
              "description": "Real Time Availability Check (RTAC) holding details",
              "additionalProperties": false,
              "javaType": "org.folio.rest.jaxrs.model.RtacHolding",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The FOLIO id of the holding (item)"
                },
                "location": {
                  "type": "string",
                  "description": "The location of the holding"
                },
                "callNumber": {
                  "type": "string",
                  "description": "The call number of the holding"
                },
                "status": {
                  "type": "string",
                  "description": "The availability status of the holding"
                },
                "dueDate": {
                  "type": "string",
                  "format": "date-time",
                  "description": "The date when the holding will be available"
                },
                "volume": {
                  "type": "string",
                  "description": "Volume details for the holding (item)"
                },
                "temporaryLoanType": {
                  "type": "string",
                  "description": "Name of the temporary loan type for a given item"
                },
                "permanentLoanType": {
                  "type": "string",
                  "description": "Name of the default loan type for a given item"
                }
              },
              "required": [
                "id",
                "location",
                "callNumber",
                "status"
              ]
            }
          }
        },
        "required": [
          "holdings"
        ]
      }
    },
    "errors": {
      "description": "Errors",
      "type": "array",
      "items": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "description": "An error",
        "type": "object",
        "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"
        ]
      },
      "minimum": 0
    }
  },
  "additionalItems": false,
  "additionalProperties": false
}

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

"unable to process request -- constraint violation"

Response 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

Response 404

Not Found

Body

Media type: text/plain

Type: any

Example:

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",
        "$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"
        }
      ]
    }
  ]
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error