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
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@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@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
Hi, We definitely have to follow https://wiki.koha-community.org/wiki/Terminology In addition we should try and generate the DB schema of our dreams (regarding naming only!). That way we could have the REST API using it already while the code will be moving slowly in this direction. That should be a team work, but driven first by few fellows to provide a first draft. Cheers, Jonathan On Fri, 24 Mar 2017 at 10:23 Taskula Lari <lari.taskula@jns.fi> wrote:
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@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/
Do we have any conventions for snake_case vs. notsnakecase? I don't see that in https://wiki.koha-community.org/wiki/Terminology, although it may be somewhere else in the coding guidelines. [This is probably bike-shedding that's been discussed elsewhere; please don't let me derail the discussion]. --B On Fri, Mar 24, 2017 at 10:34 AM, Jonathan Druart < jonathan.druart@bugs.koha-community.org> wrote:
Hi, We definitely have to follow https://wiki.koha- community.org/wiki/Terminology In addition we should try and generate the DB schema of our dreams (regarding naming only!). That way we could have the REST API using it already while the code will be moving slowly in this direction. That should be a team work, but driven first by few fellows to provide a first draft. Cheers, Jonathan
On Fri, 24 Mar 2017 at 10:23 Taskula Lari <lari.taskula@jns.fi> wrote:
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@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/
_______________________________________________ Koha-devel mailing list Koha-devel@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/
I will add this to next meeting's agenda. Things to think by the time of the meeting so we can vote on those: - bike-shedding about parameters names (I'll attach screenshots of the API docs using three different conventions so it gets clearer. - Possibly missing terminology to add to the wiki. - Make it explicit that the terminology wiki conforms a guideline and not just a bike-shedding place. Regards El vie., 24 de mar. de 2017 2:11 PM, Barton Chittenden < barton@bywatersolutions.com> escribió:
Do we have any conventions for snake_case vs. notsnakecase?
I don't see that in https://wiki.koha-community.org/wiki/Terminology, although it may be somewhere else in the coding guidelines.
[This is probably bike-shedding that's been discussed elsewhere; please don't let me derail the discussion].
--B
On Fri, Mar 24, 2017 at 10:34 AM, Jonathan Druart < jonathan.druart@bugs.koha-community.org> wrote:
Hi, We definitely have to follow https://wiki.koha-community.org/wiki/Terminology In addition we should try and generate the DB schema of our dreams (regarding naming only!). That way we could have the REST API using it already while the code will be moving slowly in this direction. That should be a team work, but driven first by few fellows to provide a first draft. Cheers, Jonathan
On Fri, 24 Mar 2017 at 10:23 Taskula Lari <lari.taskula@jns.fi> wrote:
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@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/
_______________________________________________ Koha-devel mailing list Koha-devel@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/
_______________________________________________ Koha-devel mailing list Koha-devel@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
participants (4)
-
Barton Chittenden -
Jonathan Druart -
Taskula Lari -
Tomas Cohen Arazi