Biblios endpoint RFC
Bugs
- Original bug implementing the functionality (Patch doesn't apply)
- Add MARC-related content/type definitions (NSO)
- Add API routes to update and create biblio record (New)
Actions and routes
General proposed routes.
| Description | Action | Proposed path |
| Get biblio | GET |
/biblios/{biblio_id}
|
| Add biblio (from some metadata format) | POST |
/biblios |
| Overwrite a biblio | PUT |
/biblios/{biblio_id}
|
| Delete a biblio | DELETE |
/biblios/{biblio_id}
|
Adding a biblio record
The current data model for biblios (including the biblioitems table) consists of several attributes related to bibliographic records, along with an ID (biblionumber), with associated metadata records. Several serialization formats and schemas could be supported.
Adding a new bibliographic record will require passing the record on the request body, serialized in a way that Koha can handle and both the serialization format and metadata schema need to be passed in the Content-Type header. Currently, Koha supports creating new biblio entries starting with anything that can be represented by a MARC::Record object. The API won't impose any limitation in this sense. Biblios could eventually created out of JSON objects representing a biblio+biblioitems table row. It won't be supported right now, but the API design won't impose a limit on this regard.
Getting a biblio record
A biblio record will be a JSON object that resembles the biblio+biblioitems rows. Fields will be added to specify the underlying serialization format and metadata schema. This way the consumer will be able to request the metadata record.
When the request is just JSON, this endpoint will return the Biblio+biblioitems rows. Likewise for adding new rows of we ever support that. I haven't finished that part of this RFC. -- tcohen
Metadata format handling
Any write operation will require Content-type to be specified. Conversely, any read operation will require the Accept header to be present.
Valid options (as of today) will be:
| Format | Content-type | Spec |
MARC |
application/marc; schema=<$schema> |
application/marc |
MARC-in-JSON |
application/marc-in-json; schema=<$schema> |
application/marc-in-json |
MARCXML |
application/marcxml+xml; schema=<$schema> |
application/marcxml+xml |
Neither the MARC or MARCXML content-type specs define valid parameters, but it is safe to use them to specify the schema to be used/required. Koha should return an error code if the content-type/schema combination is not valid. For the current MARC-specific serialization formats on this spec, this is basically for choosing between different MARC flavours, case insensitive.
MARC-in-JSON
There's no RFC defining the application/marc-in-json mime-type. Sierra uses it, and it should be safe to use as there's a really constrained context in which this is going to be used.
Comments
Makes sense to me! --Kfischer 05:46, 30 March 2018 (EDT)
Regarding POST and PUT content-types - OpenAPI spec v2 does not support multiple parameter schemas for different content-types. Additionally, as of now, our version of Mojolicious::Plugin::OpenAPI does not support a JSON-style string explicitly defined as "string" in body. It seems to automatically convert it into an object and then complain about object given instead of a string. This gives us headache with handling both application/(marc-in-)json and application/marc*. OpenAPI 3 supports all this, so perhaps we should first put effort in upgrading our spec to v3. --Lari 14:18, 14 March 2020 (UTC)
Devs working on /biblio endpoint may seek example from similar feature https://github.com/KohaSuomi/Koha/pull/159 where we support multiple content-types for POST/PUT as well. Please note that it's based on old Koha 17.04 with heavy forking --Lari 22:12, 17 March 2020 (UTC)