[Koha-devel] REST API object property naming

[Taskula Lari]

Hello fellow Koha devs,

As the REST API is moving forward, me and Tomás had a discussion on 
parameter and object property naming convention and how we should expose 
column names to API consumers. Since we have already renamed multiple 
objects in Koha (e.g. borrowers -> patrons, branches -> libraries etc), 
we should discuss naming convention in REST API and maintain a 
consistency throughout.

For those who have not been following REST API development, I will 
quickly brief the current method that most REST API patches in Bugzilla 
have implemented: The endpoint name in most cases uses name of the 
corresponding Koha-object, for example /api/v1/patrons, /api/v1/holds, 
/api/v1/cities and so on. This is pretty clear. We then fetch one or 
more rows from the database via Koha-objects and simply convert them 
into JSON.

The issue is that many of our database tables have inconsistency between 
column names and the Koha-object names - meaning that currently 
/api/v1/patrons returns a borrowernumber, /api/v1/holds a reserve_id and 
so on. The API user does not care how we internally call our objects and 
its parameters but only wants to see a clear and consistent naming 
convention. Therefore /api/v1/patrons should return a "patron_id", 
"library_id".

Do we want this? What about implementation, how do we want Koha-objects 
to work with this? Koha::Object currently contains a TO_JSON method that 
could be suitable for outputting renamed keys. What about input when the 
keys are renamed, how do we want to convert them back? Any other 
comments or ideas?

Lari Taskula
Koha-Suomi Oy