Timeline for Internal REST API versioning strategy
Current License: CC BY-SA 3.0
5 events
when toggle format | what | by | license | comment | |
---|---|---|---|---|---|
May 23, 2023 at 11:21 | comment | added | Pithikos | This is good in theory. For DX, versioning in URL is 1000x easier to work with. | |
Apr 10, 2018 at 14:31 | comment | added | Nicholas Shanks | @marstato Whilst you could negotiate on a custom header, and that would be still better than encoding versions into a URL, you would lose the semantics that Content-Type already possesses, namely that the thing that is different is the binary representation, and to be able to understand the document (rather than just parse it) you need to speak "application/vnd.my-doc-v2+json" rather than just "text/json". You would also have to make up a new header and clients would have to add additional code for that. | |
Apr 10, 2018 at 14:25 | comment | added | Nicholas Shanks |
@marstato Putting the version into a header, rather than e.g. the URL, allows clients to negotiate for it using Accept & Vary semantics that are already well understood and deployed by middleware like caching proxies, but still share an identifier, the URL, between v1 and v2 clients. And specifically using the Content-Type header is ideal as different formats (v1 and v2) have different binary representations, just as JPEG and PNG versions of an image have different binary representations but reflect the same resource (in the HTTP sense of the word "resource").
|
|
Apr 8, 2018 at 17:28 | comment | added | marstato |
Why put the version into the content type? other versions often also come if different semantics and business logic. Why not put the version into a separate header and leave the content type to be application/json (or whatever format you happen to use)
|
|
Mar 9, 2018 at 13:52 | history | answered | Nicholas Shanks | CC BY-SA 3.0 |