7

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)
| improve this question | | | | |
9

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.

| improve this answer | | | | |
  • That makes perfect sense as the what to do, and it allows me to just request Version=1 for now and deal with how to actually route it if/when I actually need to version the API. Thanks! – Jeremy Hutchinson May 3 '13 at 10:28
  • for version 2 of the resource request how did you route to the (Resource)2Controller using only the version of request in accept/content type header using MIME type properties? – user20358 Apr 22 '15 at 15:40
  • Why do I feel like we're right back in DLL hell adding int Foo2() methods to our interfaces and maintaining the original Int Foo() forever all of a sudden?... – RubberDuck Oct 1 '15 at 23:49
1

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.

| improve this answer | | | | |
  • If it never needs to change (beyond additive) then it doesn't need to care. If it does change with external consumers or released clients in the wild, then you absolutely need to change. Look @ github API - they're on version 3. Ours has 4 WebService versions and now a RESTful new API. – bryanmac May 2 '13 at 1:09
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:

| improve this answer | | | | |
  • 2
    If you're also trying to be RESTful, this breaks the permalink to a resource which is critical especially if integrated services persist those permalinks – bryanmac May 2 '13 at 0:42
  • This will all depend on the scenario wouldn't it? if at one point you have a major change in names or signatures of methods and you don't want breakage of existing functionality the only way to achieve this is to have the two versions running side by side (like when Facebook changed everything to the Graph API) – amhed May 2 '13 at 1:09
  • OK I just read your post and feel I was just schooled on the subject. Thanks for that =D – amhed May 2 '13 at 1:10
  • 1
    BTW, versioning in the URL is very common (and simple) and not a problem if you're not trying to be RESTful, others aren't persisting etc... Our SOAP API did this, I believe twitter did it, so it is an option - just has some considerations :) – bryanmac May 2 '13 at 1:15

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.