[Koha-devel] REST API object property naming

[Tomas Cohen Arazi]

Good starting point for this conversation, Lari. When I wrote the patches
for an /acquisitions/vendors endpoint (18120 / NSO) [1] the first thing I
noticed was column/property names were inconsistent, some where not used at
all, etc. So I wrote a couple functions (_to_api and _to_model) to deal
with back and forth data transformation. I will of course file a bug
proposing to rename the columns, and remove unused ones. But in the
meantime, this major refactoring shouldn't halt the REST api development.

I am all for using names that are not tied to our legacy names in the code,
specially when we have consensus on the rename (patrons, holds and
libraries are clear examples). It is not trivial (or even worth) renaming
borrowernumber columns in the code, but I think we have the chance to
expose a consistent API and we need to do do the effort.

So,
+1 patron_id (borrowernumber means nothing on the API, as it all refers to
patrons)
+1 library_id (branchcode, same as above)

Kind regards.

[1] https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18120

El vie., 24 mar. 2017 a las 10:23, Taskula Lari (<lari.taskula at jns.fi>)
escribió:

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
_______________________________________________
Koha-devel mailing list
Koha-devel at lists.koha-community.org
http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
website : http://www.koha-community.org/
git : http://git.koha-community.org/
bugs : http://bugs.koha-community.org/

-- 
Tomás Cohen Arazi
Theke Solutions (https://theke.io <http://theke.io/>)
✆ +54 9351 3513384
GPG: B2F3C15F
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.koha-community.org/pipermail/koha-devel/attachments/20170324/17187a86/attachment.html>