3 ms·
If you're writing a client which is sensitive to the resource representation changing over time and you're using something that calls itself an API, hopefully o
by ldh 14y ago
If you're writing a client which is sensitive to the resource representation changing over time and you're using something that calls itself an API, hopefully one would skim the provided docs enough to see that you might want to explicitly state the version you want. Or notice that the Content-Type returned for the generic application/json query is a versioned type.
I acknowledge that it's a little more work than just banging out a versioned URI, but it's not that much work and I like the URI/conceptual purity.
- zimbatm 14y ago> and I like the URI/conceptual purity. This sums up pretty much the whole debate. Pragmatics vs idealists.
- j_s 14y agoThe interesting thing is that it is a false dichotomy - it's easy enough to implement both. Perhaps enhanced by adding a flag on the documentation to flip between pragmatist/idealist so each only sees their one way to do it right...
- Osiris 14y agoAnother solution that I've seen is to use a custom header in the request such as X-Api-Client-Version: 1 If the header isn't provided, then the most current version of the API is called. The nice thing about this is that it doesn't 'pollute' the URI and it allows for automatic upgrading to the latest version of the API if the developer doesn't specify the API version.
- bryanh 14y agoSilently and automatically upgrading an API is a horrible idea.
- DropkickM16 14y agoIt depends on how your API is designed. If it's a tightly coupled RPC-style API or something, this is obviously a bad idea because you'll break every client that didn't see the change coming. But the goal of designing APIs in a hypermedia style is to eliminate this tight coupling and include in each response all the information that a client would need to traverse the application's states. When this is designed properly, it is easier to change the API's functionality without breaking existing clients. The web is a great example of this (although you may have to squint a bit to see it). Browsers don't need to add additional code or install plugins to handle forms with different fields or links to content of different types, because the semantics of those elements and their interactions are well-defined.