Why is it considered best practice to use the content type header for API versioning? It always seemed like a hack to me. Url versioning makes much more sense if you consider that your API is a resource and the content of your API is a subresource. E.G. GET /v1/post/1/comment/456 would be semantically equivalent to "give me comment with id 456, which belongs to post with id 1, which belongs to api of version 1".
Can anyone explain why using different verbs (PUT, PATCH, ...) is preferable to using just POST with an additional parameter (e.g. POST action="add")? It seems like the author's distinction between POST, PUT and PATCH seems rather arbitrary...
Good article, summarise what I like and don't like.<p>I wish it would delve deeper into versioning with some code samples.
The way I've done it in the past is just inherit from a controller and just override an action as well as the json-builder. But that because unmaintainable after version 3 or so.<p>I like how Relay/GraphQL sorta abstracts that away, but Ive had a hard time figuring out how to make that work with the ORM (Active Record) so abandoned for now.
The elephant in the room for me is that while HATEOAS is mentioned, the impression I get from posts from developers online is that people program against a pre-agreed API format.<p>That's different to REST's automated discoverability for REST API clients.
This is a great guide. Side note: Is there an example of implementing OAuth2 from API developers perspective and from API Consumers perspective? language agnostic but Go or Java preferred.