In a large service with multiple consumers and integrated services, here's some principles and guidelines we followed to be RESTful over our web api. If you're not trying to be RESTful etc... and just want a simple http api, then it may not apply.
- A resource is identified by a RESTful URL (site.com/api/user/6).
- That URL needs to be a permalink (always refers to that resource). External services and consumers of the API can persist that permalink
- Different versions of the client may ask for site.com/api/user/6 and depending on version, may get a different representation (version) of the resource.
- We try hard to get it right, review APIs, etc... but we realize we won't get it right sometimes and want the ability to be able to version it and get it right.
We considered putting the version in the URL, but that breaks key RESTful principles.
Good read on web api design and versioning
What we did (basically, waving hands over details):
- Put version of request in accept/content type header using MIME type properties: application/json;version=2 (we considered vendor MIME types which BTW, github uses). We also support passing in querystring for web mashup scenarios.
- We customized the routing so a request for version 2 of the resource request would route to the (Resource)2Controller.
- On an http OPTIONS request, the server would iterate over the routes and expose the resources, available route templates and min/max version (our custom attribute put on the controller/classes).
- The client knows what version it is so the first thing the client did is an OPTIONs request and negotiated the max version the client and server understands then it would send that in the header.
- Since the server has multiple controllers, it's capable of handing back different versions of that resource.
- Even though we're capable of versioning the resource, we refrain and take an purely additive approach if possible (older clients ignore extra properties on deserialization). iOS will do this fine since it's just extra data in the dictionaries.
- One benefit we got from the OPTIONs exposing routes, was we actually avoid path math on the client. It knows what version it is - the http client passes in a dictionary and urls are formatted using the server advertised routes.
I am considering writing a blog and sharing how we integrated into web api to version our resources. If I do, I will follow up here with a link.