Biblios endpoint RFC

From Koha Wiki

Jump to: navigation, search

Contents

Bugs

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)