RESTful API v2

[sekjal]

Libki's API has grown organically over the years. For example, clients are listed at /api/public/datatables/clients, while prints and reservations are under /public/api/datatables/prints and /public/api/datatables/reservations. But Reservations creation/deletion are found at /api/public/reservations/... and let's not even start with Users.

I propose that a new, unified, RESTful API be developed in parallel with what we currently have. This would serve at /api/v2/..., and provide full CRUD support for the key objects in Libki. Once completed, the web UI would be converted over to use this new API for all its interactions. The Client, Print Manager and Print Station APIs (already versioned) would be kept longer for better backwards compatibility.

This would probably need to be done AFTER increasing permissions granularity.

[kylemhall]

Moving as much logic out of the old client API endpoints into "business logic" modules that could be used in both the old and new APIs would allow for a period of time where both versions are available, would allow for some length of transition period to give libraries time to upgrade clients instead of needing them all to be done in one fell swoop.

Another possibility would be to leave the old API as is and embargo new code affecting the client API for a release cycle or two to simplify the transition during client migration.

[sekjal]

I'm thinking we should leave the existing API alone, and create all new endpoints within the v2 framework. Equivalent endpoints of v1 functionality can be added to v2 as development cycles permit; changes that only impact Libki Server would be the easiest to implement, whereas any changes to api endpoints used by Client, Print Manager or Print Station would need corresponding updates in those components, and LOTS of communication about compatibility and upgrade paths

[jfmartinezm]

I agree that the existence of a REST API would greatly include the value of Libki as an application, it's something I have been missing already for a long time. As per the transition, it could be done by using something similar to the strangler pattern for modernizing monoliths, where functionality is built into a new API in parallel with the old one until the new one takes over. If you are interested in this approach, we are going to use it in another unrelated project that also needs to split a monolith server into several smaller services using the necessary APIs.

As per the client, things could go even further; the interface part of the user facing components (Client, Print Manager, Print Station) could be built as a web app over the new REST API, simplifying the development of the clients and leaving only a small system part on them, that could then operate as a separated system service also using the same REST API.

[kylemhall]

It would be good to keep the v1 api intact as much as possible. Logic should be moved into models/business logic modules as much as possible Libki has a strong history of backwards and forwards compatibility that has limited the need for client upgrades unless needed for bug fixes or to get a needed feature the newer servers support. A full unit test suite for the V1 API would be a good start to prevent V1 regressions as everything is rejiggered under the hood.

[jfmartinezm]

My suggestion, in any case, was to build a completely new API for the web interface and possible new clients, while keeping the original one around as long as needed, as I understood from the original post. Anyway, I agree that, even to build that new API, it would be important to rearrange logic into models or business logic modules, and I also see the importance of a test suite to keep the current API from breaking. I'm afraid I'm not proficient enough in Perl to write that tests myself, but maybe getting some examples of that tests I could try and modify them to expand the amount of cases they cover.