How to version REST URIs

by

Do not version URLs, because …

  • you break permalinks
  • The url changes will spread like a disease through your interface. What do you do with representations that have not changed but point to the representation that has? If you change the url, you break old clients. If you leave the url, your new clients may not work.
  • Versioning media types is a much more flexible solution.

Assuming that your resource is returning some variant of application/vnd.yourcompany.user+xml all you need to do is create support for a new application/vnd.yourcompany.userV2+xml media type and through the magic of content negotiation your v1 and v2 clients can co-exist peacefully.

In a RESTful interface, the closest thing you have to a contract is the definition of the media-types that are exchanged between the client and the server.

The URLs that the client uses to interact with the server should be provided by the server embedded in previously retrieved representations. The only URL that needs to be known by the client is the root URL of the interface. Adding version numbers to urls only has value if you construct urls on the client, which you are not suppose to do with a RESTful interface.

If you need to make a change to your media-types that will break your existing clients then create a new one and leave your urls alone!

And for those readers currently saying that this makes no sense if I am using application/xml and application/json as media-types. How are we supposed to version those? You’re not. Those media-types are pretty much useless to a RESTful interface unless you parse them using code-download, at which point versioning is a moot point.

More Related Contents:

  1. Best practices for API versioning? [closed]
  2. HTTP GET with request body
  3. Representational state transfer (REST) and Simple Object Access Protocol (SOAP)
  4. HTTP POST with URL query parameters — good idea or not?
  5. REST API Best practice: How to accept list of parameter values as input [closed]
  6. When do I use path params vs. query params in a RESTful API?
  7. Transactions in REST?
  8. How to QUEUE a new build using VSTS REST API
  9. What is RESTful programming?
  10. secure api data from calls out of the app
  11. S3 REST API and POST method
  12. RESTful way to create multiple items in one request
  13. REST Content-Type: Should it be based on extension or Accept header?
  14. Are there any naming convention guidelines for REST APIs? [closed]
  15. How to expose a RESTful Web Service using Meteor
  16. REST vs JSON-RPC? [closed]
  17. What’s the currently recommended way of performing partial updates with Web API?
  18. REST api: requesting multiple resources in a single get [duplicate]
  19. How to create new build pipeline using Azure DevOps REST API?
  20. Delete multiple records using REST
  21. What is the difference between a HTTP-Get and HTTP-POST and why is HTTP-POST weaker in terms of security
  22. How do I get the body of a web request that returned 400 Bad Request from Invoke-RestMethod
  23. Call a Server-side Method on a Resource in a RESTful Way
  24. RESTful – What should a DELETE response body contain
  25. Place API key in Headers or URL
  26. Curl retry mechanism
  27. The MAC signature found in the HTTP request ‘…’ is not the same as any computed signature
  28. Response status code for searches in REST APIs
  29. Status code when deleting a resource using HTTP DELETE for the second time
  30. Avoid duplicate POSTs with REST

Leave a Comment