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
| Table of Contents |
|---|
Request
For migration the proposed endpoints could be implemented as an extension.
| Task | Method | Path | PostParms |
|---|---|---|---|
| Inquirer information about one instance defined by UUID | GET | /rtac/uuid/{instance_uuid} | |
| Inquirer information about one instance defined by HRID | GET | /rtac/hrid/{instance_uuidhrid} | |
Inquirer information about multiple instances defined by UUID | POST | /rtac/uuid | List of UUIDs |
Inquirer information about multiple instances defined by HRID | POST | /rtac/hrid | List 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
| Code Block | ||
|---|---|---|
| ||
{
"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
| Anchor | ||||
|---|---|---|---|---|
|
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'.
| Code Block | ||
|---|---|---|
| ||
{
"$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
- Explicit naming of the possible pickup locations.
- A brief mode (more like the current RTAC)
Discussion
Pros
Completeness. The only unmet need I can see is the lack of explicitly provided possible pickup locationsExisting APIs (added by Julian Ladisch)
mod-inventory-storage already has these APIs:
/inventory-hierarchy/items-and-holdings (this is used by
edge-rtac/mod-rtac)
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
- No simplification. Simplification is most often the first goal when designing The suggested API is too verbose. The response with all the data seems to be bloated. Keeping an API like RTAC . Since simplification is also synonymous with loss of variance, this approach does not cover all real-world librariessimple is usually a good design pattern . But any aggregation seems to be a loss of needed details.