search

amiv-eth / amivapi

The REST API behind most of AMIV's web services.
http://api.amiv.ethz.ch/docs
GNU Affero General Public License v3.0
30 stars 6 forks source link

API Version #16

Closed cburchert closed 8 years ago

cburchert commented 9 years ago

The API should send a version string, which can be used to provide backwards compatibility when the API is changed.

cburchert commented 9 years ago

If we want to have some kind of compatibility probably the apps will get outdated instead of the API. Therefore apps should send some API version string and we should react to that. Is that something we want to support or do we rather setup something like /legacy where older versions can be found?

fubu commented 9 years ago

From a pure REST point of view, you'd version the hypermedia type (using a custom MIME type in the Accept header, e.g. application/vnd.amivapi.v2+json). Requests without such a header would probably be served the latest version/hypermedia type. The common solution of putting a version identifier into the URL of course allows to hit different version endpoints from the browser, but that is already not always trivial anymore thanks to the Authorization header for some endpoints. But all in all, it's the method almost everyone uses today in some way or another (when everybody is doing it wrong, we can as well, right?).

I think an important aspect before deciding on a specific scheme is to think about how much "legacy" you want to support in the long term. When do you shut down the "v2" api? After 2 years? After releasing v5? Having "legacy versions" still active means you must find some way to run the old code along with the new code at any point in time. (And when an old API version gets shut down, you probably still want to serve an HTTP response of 410 Gone for a certain period of time to clearly tell outdated clients that this version is not supported anymore...)

I would say as long as there are not many clients using the API, take your time exploring the options and their limitations/consequences.

NotSpecial commented 8 years ago

Rolling release :D

Being serious: I think this would add a lot of complexity and confusion. We have decided against any legacy support.