I have been researching versioning for RESTful API's and trying to figure out how to apply it to WebApi.
So far I have concluded that WebApi has no built-in versioning.
This is a shame because if I implement my own, I would assume that the ApiDocumentation class would then be inaccurate.
Currently my choice is to use vendor mime-types and implement them using a custom IHttpActionSelector.
I am going to read the headers, and load the right version based on a [Version("1.0")] attribute.
My superiors don't believe me that WebApi doesn't have versioning baked in. Am I wrong?
Currently my choice is to use vendor mime-types and implement them using a custom IHttpActionSelector.
Could you please elaborate more on this? are you trying to post different versions of data and would like that to be handled by different actions OR to be handled by the same action but has to go through different versions of formatters?
This is for making breaking changes. When a breaking change is introduced we have to alter the whole endpoint because the old one will no longer fit. This is not a simple formatter change.
-->
Accept: Application/vnd.company+json; Version=1.0
-->
/resource/1
public Resource1 GetV1(int id)
-->
Accept: Application/vnd.company+json; Version=2.0
-->
/resource/1
public Resource2 GetV2(int id)
To answer your last question, no, versioning is not built into Web API. I don't believe any MS tool includes versioning for anything other than their actual tools, e.g. MVC 4. As Brock noted, versioning is not agreed upon as necessary. I would actually be interested
In learning about any tool that provides versioning out of the box. I would imagine it would have to be very opinionated.
As Kiran mentioned, media (MIME) types are related to for matters in Web API. You could also work out a mechanism for routing areas a la MVC if you wanted to pass a uri parameter through routing. When you say breaking change, do you mean a fundamental change
in the underlying data model or just rendered output? If the former, you would likely be better off with a whole new project routed under a version path segment. Otherwise formatters should be sufficient.
Below is a good video on REST and this guy's impressions on how to do versioning with REST. I'm going to follow one of his patterns which is /api/1.0/Object
My superiors don't believe me that WebApi doesn't have versioning baked in. Am I wrong?
Web API was built to be a faithful implementation of the HTTP Standard. HTTP says nothing about versioning of resources/representations. There are many different perspectives on how you can do versioning in Web APIs and therefore it would have been irresponsible
of Microsoft to express a preference in the implementation of Web API.
Based on the last 5 years of building web APIs on the Microsoft platform, I do believe the idea of versioning is highly overrated. I have not needed it yet.
digitalpacma...
Member
183 Points
148 Posts
Any movement on versioning?
Aug 14, 2012 09:39 PM|LINK
I have been researching versioning for RESTful API's and trying to figure out how to apply it to WebApi.
So far I have concluded that WebApi has no built-in versioning.
This is a shame because if I implement my own, I would assume that the ApiDocumentation class would then be inaccurate.
Currently my choice is to use vendor mime-types and implement them using a custom IHttpActionSelector.
I am going to read the headers, and load the right version based on a [Version("1.0")] attribute.
My superiors don't believe me that WebApi doesn't have versioning baked in. Am I wrong?
Kiran Challa
Participant
1460 Points
285 Posts
Microsoft
Re: Any movement on versioning?
Aug 14, 2012 09:47 PM|LINK
Could you please elaborate more on this? are you trying to post different versions of data and would like that to be handled by different actions OR to be handled by the same action but has to go through different versions of formatters?
Kiran Challa
digitalpacma...
Member
183 Points
148 Posts
Re: Any movement on versioning?
Aug 14, 2012 10:07 PM|LINK
This is for making breaking changes. When a breaking change is introduced we have to alter the whole endpoint because the old one will no longer fit. This is not a simple formatter change.
BrockAllen
All-Star
28052 Points
4996 Posts
MVP
Re: Any movement on versioning?
Aug 14, 2012 10:47 PM|LINK
Versioning is a tricky topic. Some think versioning is an anti-pattern. Some think it's as easy as changing the URL.
I'd suggest checking out the API craft group where there's lots of good discussion (you'll need a google account):
https://groups.google.com/forum/?fromgroups#!topic/api-craft/iInGY4vmgro[1-25]
DevelopMentor | http://www.develop.com
thinktecture | http://www.thinktecture.com/
digitalpacma...
Member
183 Points
148 Posts
Re: Any movement on versioning?
Aug 14, 2012 11:00 PM|LINK
I'm going based on this, and already have a plan on how to version. I'm just having issues implementing it.
http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http
panesofglass
Participant
758 Points
242 Posts
Re: Any movement on versioning?
Aug 15, 2012 02:56 AM|LINK
panesofglass
Participant
758 Points
242 Posts
Re: Any movement on versioning?
Aug 15, 2012 03:10 AM|LINK
NickTullos
Member
7 Points
18 Posts
Re: Any movement on versioning?
Aug 15, 2012 12:39 PM|LINK
Below is a good video on REST and this guy's impressions on how to do versioning with REST. I'm going to follow one of his patterns which is /api/1.0/Object
http://blog.apigee.com/detail/restful_api_design/
Darrel Mille...
Member
176 Points
56 Posts
Re: Any movement on versioning?
Aug 15, 2012 02:08 PM|LINK
Web API was built to be a faithful implementation of the HTTP Standard. HTTP says nothing about versioning of resources/representations. There are many different perspectives on how you can do versioning in Web APIs and therefore it would have been irresponsible of Microsoft to express a preference in the implementation of Web API.
Based on the last 5 years of building web APIs on the Microsoft platform, I do believe the idea of versioning is highly overrated. I have not needed it yet.
digitalpacma...
Member
183 Points
148 Posts
Re: Any movement on versioning?
Aug 15, 2012 03:13 PM|LINK
@nick
It is straight up against HATEOS to put the version in the URL.