I’m starting a side project, the first stage will be a building a web application with MVC, in later stages we will be adding clients for mobile platforms. My thought was to create one API that all of the applications (web and mobile) go through to get/save data.
Because these different platforms will be on different release cycles I’ll need a way for, say IPhone, to work with one version of the API while the website is using an updated version. What’s the best way to do that?
My ideas so far are:
- Create a separate project to host the MVC Web API and host that in a subdomain or in a subfolder of the root site. Then either reference the DLL directly or reference it through the web (seems like an unnecessary http call)
- House the API within the MVC project that will be the website and try to version it based on url in there. I did some quick testing with that this morning and wasn’t able to get it to work, it always resided at api (I couldn’t get it to reside at api_v2)
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.
Key Principles:
- 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.
https://stackoverflow.com/questions/389169/best-practices-for-api-versioning
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.
3
Your API shouldn’t care about who/what is consuming it. The API provides a contract and fulfills it. It is up to the consumer to know what to do with the result. I don’t see why your iPhone and web app would need a different contract.
1
I concur with what Jean-Bernard said. You should have one API so everybody can access it.
But that said, you will eventually have more than one version. You would manage that on different branches on your Source Control system. If you ever need to have more than one version published I recommend using subdomains:
- http://api.yoursite.com
- http://apiv2.yoursite.com
4