Consider offering old API versions after major release
Opened this issue · 1 comments
The latest major release of version 2.0 broke Cocoda as it was configured to only be compatible with JSKOS API 1.0. Should we offer a way to access old API versions somehow?
An alternative would be to update our deployment that multiple JSKOS Server instances will keep running, e.g. https://coli-conc.gbv.de/api/v1, https://coli-conc.gbv.de/api/v2, etc., using the same database thus accessing the same data. Of course, at some point we should remove older versions, but we could keep them around for a few months or so. https://coli-conc.gbv.de/api/ could still refer to the latest API.
What do you think, @nichtich?
I like the idea of API versioning with https://coli-conc.gbv.de/api/v1/, https://coli-conc.gbv.de/api/v2/ and https://coli-conc.gbv.de/api but I'm nure sure how to best deploy two instances of different version it on the same database without risiking database corruption. Proving two API versions on the same instance is additional complexity in jskos-server but seems doable and would support removal of deprecated endpoints.
Best practice for API versioning would be to redirect current https://coli-conc.gbv.de/api/* to a versioned API URL.
api/v1 would support all current endpoints (possibly minus the new concepts andpoint) and api/v2 would not support deprecated endpoints.
In any case there will always be breaking clients because at some day, support of an old API version should be dropped.