Proposal for a new RTAC

As already mentioned, I assume that a redesign might be more effective than patching RTAC.
As a basis for of further discussion I'd like to  share a first approach.

Abstract

The general idea is to expose all relevant information in the response. In other words, the new RTAC should simply provide  all (unclassified) attributes of the objects 'holding', 'item', and 'location'. This will allow a library to use all attributes of these objects to pass hints to a discovery system. (e.g. the public note fields).
The  current RTAC  provides only a subset of all possible information. Its limitations are well documented.

TOC

Request

For migration the proposed endpoints could be implemented as an extension.

TaskMethodPathPostParms
Inquirer information about one instance defined by UUIDGET/rtac/uuid/{instance_uuid}
Inquirer information about one instance defined by HRIDGET/rtac/hrid/{instance_hrid}

Inquirer information about multiple instances defined by UUID
(needs additional level in the schema of the response)

POST/rtac/uuidList of UUIDs

Inquirer information about multiple instances defined by HRID
(needs additional level in the schema of the response)

POST/rtac/hridList of HRIDs

Notes:

  • HRID as query parameter is indispensable for most German libraries.
  • Since clients are capable to do asynchronous concurrent requests, it seems be outdated to provide a batch mode (POST endpoints).

Response

According to current design patterns JSON is assumed as transport format for the RTAC response.

Example

Short hypothetical response to http://somehost/rtac/hrid/12345678

{
  "id" : "12345678",
  "holdings": [
    {
      "id": "28ead097-5e3d-44fe-b647-ec982a1e4433",
      "hrid": "a",
      "type": "electronic",
      "suppressDiscovery": false,
      "somethingUnknown": "Newly introduced attribute in the holding record",
      "items": [
        {
          "id": "28ead097-5e3d-44fe-b647-ec982a1e4413",
          "hrid": "1",
          "callNumber": "29K 216,2.Aufl.",
          "status": "available",
          "permanentLoanType": "lendable",
          "location": {
            "id": "Lehrbuchsammlung_3",
            "displayName": "Main building",
            "type": "Freihand",
            "somethingUnknown": "Newly introduced attribute in the location record"
          },
          "somethingUnknown": "Newly introduced attribute in the item record"
        }
      ]
    }
  ]
}


Schema

Preliminary definition  the response. This version is far from complete. In the final version it should be capable to transport all attributes of 'holding', 'item' and 'location'.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "RTAC Holding Schema",
  "description": "Real Time Availability Check (RTAC) holding details.",
  "type": "object",
  "required": [
    "id",
    "holdings"
  ],
  "properties": {
    "id": {
      "description": "Id of the requested instance ('uuid' |'hrid')",
      "type": "string"
    },
    "holdings": {
      "type": "array",
      "description": "List of holdings",
      "holding": [
        {
          "$ref": "/schemas/rtac/holding"
        }
      ]
    }
  },

  "$defs": {
    "holding": {
      "$id": "/schemas/rtac/holding",
      "description": "holding details. (https://wiki.folio.org/pages/viewpage.action?pageId=54888355)",
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "description": "Uniform id of this holding record",
          "$ref": "/schemas/rtac/uuid"
        },
        "hrid": {
          "description": "Human readable id of this holding record",
          "type": "string"
        },
        "type": {
          "description": "Material type of this expression",
          "type": "string"
        },
        "urls": {
          "description": "List of possible URLs",
          "$ref": "/schemas/rtac/urls"
        },
        "uri": {
          "description": "?",
          "type": "string"
        },
        "suppressDiscovery": {
          "description": "Additional flag for the visibility",
          "type": "boolean"
        },
        "location": {
          "description": "Default storage room",
          "$ref": "/schemas/rtac/location"
        }
      },
      "items": {
        "type": "array",
        "description": "List of items",
        "item": [
          {
            "$ref": "/schemas/rtac/item"
          }
        ]
      }
    },

    "item": {
      "$id": "/schemas/rtac/item",
      "description": "Description of one item. (https://wiki.folio.org/pages/viewpage.action?pageId=54888358)",
      "type": "object",
      "properties": {
        "id": {
          "description": "Uniform id of this item",
          "$ref": "/schemas/rtac/uuid"
        },
        "hrid": {
          "description": "Human readable id of this item",
          "type": "string"
        },
        "callNumber": {
          "description": "The main call number (aka. shelf mark) of this item",
          "type": "string"
        },
        "barcode": {
          "description": "The Barcode of this item",
          "type": "string"
        },
        "acquisitionNumber": {
          "description": "?",
          "type": "string"
        },
        "status": {
          "description": "The current availibility status of this item in the circulation system",
          "type": "string"
        },
        "dueDate": {
          "description": "Item record's due date field",
          "type": "string"
        },
        "permanentLoanType": {
          "description": "The general type of loan for this item",
          "type": "string"
        },
        "temporaryLoanType": {
          "description": "The general type of loan for this item",
          "type": "string"
        },
        "location": {
          "description": "The effective storage room for this item",
          "$ref": "/schemas/rtac/location"
        }
      },
      "required": [
        "id",
        "hrid",
        "indicator",
        "status"
      ]
    },

    "location": {
      "$id": "/schemas/rtac/location",
      "description": "Storarage location refered in 'item' and 'holding' ",
      "type": "object",
      "required": [
        "id",
        "displayName",
        "type"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "displayName": {
          "type": "string"
        },
        "type": {
          "type": "string"
        }
      }
    },

    "uuid": {
      "$id": "/schemas/rtac/uuid",
      "description": "uuid for FOLIO data objects",
      "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}$"
    },

    "urls": {
      "$id": "/schemas/rtac/urls",
      "description": "List of Urls",
      "type": "array",
      "minItems": 1,
      "url": {
        "type": "string"
      }
    }
  }
}

Possible further Extensions

  1. Explicit naming of the possible pickup locations.
  2. A brief mode (more like the current RTAC)

Existing APIs (added by Julian Ladisch)

mod-inventory-storage already has these APIs:

Discussion

Pros

  • Completeness. The only unmet need I can see is the lack of explicitly provided possible pickup locations. But since the response is "complete", this information is implicit and could be detected by simple transformations.

  • Since this API has no abstractions, the implementation should be fairly straightforward.

  • Since the implementation does not need to interpret any semantics, further extensions of the inventory objects could be reproduced very quickly.

Cons

  • The suggested API is too verbose. The response with all the data seems to be bloated. Keeping an API like RTAC simple is usually a good design pattern . But any aggregation seems to be a loss of needed details.