Topic: API Versioning

[siemensikkema]

• header versus URL
• see #5 and #3

[Irving-ML-PH]

Hi, dropped by here from the MonstarLab slack channel.

So I did some (quick) research on the topic at hand and here is what I've learned,

• The dichotomy seems to be between being true to RESTful principles (Header-based) vs being pragmatic (URI-based)

• The header based approach simplifies how to ask for the correct representation of the resource. For example, In order to ask for v1 + JSON representation of a resource with the URI approach I have to set two things the URI: /v1/posts and the header Accept: application/json. On the other hand with the header-based approach this is simplified to just Accept: application/vnd.monstarlab-v1+json or Accept: application/vnd.monstarlab+json; version=1. (There were other pro-header arguments but this was the one that resonated with me the most)

• The URI approach appears to be the more battle-tested. Google & Facebook both use URI-based versioning, though I haven't found any article or post as to why they chose that particular approach.

Conclusion: I would go with the URI strategy largely for the brand-names associated with the strategy and the fact that it makes the chosen version highly visible to the API consumer.

Sources

• https://stackoverflow.com/questions/389169/best-practices-for-api-versioning
• http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http
• https://nordicapis.com/introduction-to-api-versioning-best-practices/
• https://cloud.google.com/apis/design/versioning
• https://developers.facebook.com/docs/apps/versions

[siemensikkema]

@Irving-ML-PH Thanks for your research! Yes, the URI based approach is what we'll be recommending. Not so much because the big players do it but because it's easier and clearer IMO 🙂 There are already other places where we deviate from a strict RESTful approach, for instance endpoints where we combine multiple data sources to make it easier for the frontend (think a home-feed for example).

[Irving-ML-PH]

Great! Any thoughts on how the version string should look like? I'm perfectly happy with simple ../v1/.. on the URI, though that's because I haven't designed an API that's mean for public consumption.

[siemensikkema]

@Irving-ML-PH Yeah v1, v2 etc. See my WIP PR: https://github.com/nodesagency/API-manifesto/pull/24/files