REST api: some needed changes / vote proposal

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

REST api: some needed changes / vote proposal

Tomas Cohen Arazi
Hi everyone, we've moved forward with the REST api devs, and some decisions we made at the beginning should be dealt with now, before it is too late :-D

Right now the so-called REST api consists in 5 endpoints.

Vendors:
- /acquisitions/vendors
- /acquisitions/vendors/{vendor_id}
Cities:
- /cities
- /cities/{cityid}
Holds:
- /holds
- /holds/{reserve_id}
Patrons:
- /patrons
- /patrons/{borrowernumber}
Illrequests:
- /illrequests

When implementing the vendors endpoint, I followed the api first approach, which implies we first think of the api itself, and how it is going to be used, and then think about the implementation. The result is that the exposed attribute names don't match the DB columns (because we picked more meaningful names), and (for example) unused attributes aren't even exposed.

When it comes to the previously integrated endpoints, they mostly mimick the DB structure and thus the external api consumers see things that are highly inconsistent:

We call them holds, but the ID is reserve_id instead of just hold_id, same for borrowernumber instead of patron_id.

New endpoints are being developed with this in mind, but the already implemented ones need to get fixed. As the REST api is already at its first stages I suggest we just change those attributes and notify on the release notes about the change, but it is worth being voted. So I added it to next's dev meeting agenda. It is an urgent decision, as some of fields that would be renamed, are FK for the new endpoints being developed.

I hope everyone interested on this gets involved in the discussion on this thread, and we can move forward just voting on the dev meeting.

Thanks in advance!
--
Tomás Cohen Arazi
Theke Solutions (https://theke.io)
✆ +54 9351 3513384
GPG: B2F3C15F

_______________________________________________
Koha-devel mailing list
[hidden email]
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/
Reply | Threaded
Open this post in threaded view
|

Re: REST api: some needed changes / vote proposal

Josef Moravec
Hi Tomas (and all ;)

thank you for the work on API! I like this approach.

I think as the capabilities of the API is still just small amount of Koha capabilities, and as it is fairly new, we could take this approach and just change the naming conventions in current endpoints. Better do it now and right.

Regards

Josef



st 6. 12. 2017 v 16:13 odesílatel Tomas Cohen Arazi <[hidden email]> napsal:
Hi everyone, we've moved forward with the REST api devs, and some decisions we made at the beginning should be dealt with now, before it is too late :-D

Right now the so-called REST api consists in 5 endpoints.

Vendors:
- /acquisitions/vendors
- /acquisitions/vendors/{vendor_id}
Cities:
- /cities
- /cities/{cityid}
Holds:
- /holds
- /holds/{reserve_id}
Patrons:
- /patrons
- /patrons/{borrowernumber}
Illrequests:
- /illrequests

When implementing the vendors endpoint, I followed the api first approach, which implies we first think of the api itself, and how it is going to be used, and then think about the implementation. The result is that the exposed attribute names don't match the DB columns (because we picked more meaningful names), and (for example) unused attributes aren't even exposed.

When it comes to the previously integrated endpoints, they mostly mimick the DB structure and thus the external api consumers see things that are highly inconsistent:

We call them holds, but the ID is reserve_id instead of just hold_id, same for borrowernumber instead of patron_id.

New endpoints are being developed with this in mind, but the already implemented ones need to get fixed. As the REST api is already at its first stages I suggest we just change those attributes and notify on the release notes about the change, but it is worth being voted. So I added it to next's dev meeting agenda. It is an urgent decision, as some of fields that would be renamed, are FK for the new endpoints being developed.

I hope everyone interested on this gets involved in the discussion on this thread, and we can move forward just voting on the dev meeting.

Thanks in advance!
--
Tomás Cohen Arazi
Theke Solutions (https://theke.io)
✆ <a href="tel:+54%209%20351%20351-3384" value="+5493513513384" target="_blank">+54 9351 3513384
GPG: B2F3C15F
_______________________________________________
Koha-devel mailing list
[hidden email]
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
[hidden email]
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/
Reply | Threaded
Open this post in threaded view
|

Re: REST api: some needed changes / vote proposal

Jonathan Druart
In reply to this post by Tomas Cohen Arazi
See also the previous discussion on that topic - http://lists.koha-community.org/pipermail/koha-devel/2017-March/043576.html

On Wed, 6 Dec 2017 at 12:13 Tomas Cohen Arazi <[hidden email]> wrote:
Hi everyone, we've moved forward with the REST api devs, and some decisions we made at the beginning should be dealt with now, before it is too late :-D

Right now the so-called REST api consists in 5 endpoints.

Vendors:
- /acquisitions/vendors
- /acquisitions/vendors/{vendor_id}
Cities:
- /cities
- /cities/{cityid}
Holds:
- /holds
- /holds/{reserve_id}
Patrons:
- /patrons
- /patrons/{borrowernumber}
Illrequests:
- /illrequests

When implementing the vendors endpoint, I followed the api first approach, which implies we first think of the api itself, and how it is going to be used, and then think about the implementation. The result is that the exposed attribute names don't match the DB columns (because we picked more meaningful names), and (for example) unused attributes aren't even exposed.

When it comes to the previously integrated endpoints, they mostly mimick the DB structure and thus the external api consumers see things that are highly inconsistent:

We call them holds, but the ID is reserve_id instead of just hold_id, same for borrowernumber instead of patron_id.

New endpoints are being developed with this in mind, but the already implemented ones need to get fixed. As the REST api is already at its first stages I suggest we just change those attributes and notify on the release notes about the change, but it is worth being voted. So I added it to next's dev meeting agenda. It is an urgent decision, as some of fields that would be renamed, are FK for the new endpoints being developed.

I hope everyone interested on this gets involved in the discussion on this thread, and we can move forward just voting on the dev meeting.

Thanks in advance!
--
Tomás Cohen Arazi
Theke Solutions (https://theke.io)
✆ <a href="tel:+54%209%20351%20351-3384" value="+5493513513384" target="_blank">+54 9351 3513384
GPG: B2F3C15F
_______________________________________________
Koha-devel mailing list
[hidden email]
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
[hidden email]
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/