users@jersey.java.net

[Jersey] Re: Restful Service Versioning

From: Jason Erickson <jason_at_jasonerickson.com>
Date: Thu, 5 May 2011 15:58:20 -0700

I find the approach of using content negotiation very attractive for one class of problems - i.e. the format of your resource has a new version. However, there is another class of version problems which is: my current scheme from navigating around the URL's sucks and I want to improve it.

Say, for example, I have a scheme like this: /ws/customers/42/orders/45/lineitems/15 which will return a particular line item from a particular order of customer 42, but later I decide that orders have to do with more than just customers, so I'd rather have /ws/customers/42 and /ws/orders/45/lineitems/15. If, instead, I have /ws/v2/customers/42 and /ws/v2/orders..., I can do whatever I is my new best thinking on it.

This does not resolve the issue, however, that this sort of implies that /ws/v1/customers/42 and /ws/v2/customers/42 are different when in fact they represent the same resource, if possibly a different format. So basically, I don't have a good answer for this kind of issue. Does anyone else?

On May 5, 2011, at 12:20 PM, jfarcand wrote:

> Salut,
>
> take a look at:
>
> http://barelyenough.org/blog/2008/05/versioning-rest-web-services/
>
> A+
>
> -- Jeanfrancois
>
>
> On 11-05-05 3:08 PM, Petr Jurák wrote:
>> Well, I've meant using e.g. Accept http header to get appropriate content.
>> Petr
>>
>> -----Original Message-----
>> From: Suchitha Koneru (sukoneru) [mailto:sukoneru_at_cisco.com]
>> Sent: Thursday, May 05, 2011 9:05 PM
>> To: users_at_jersey.java.net
>> Subject: [Jersey] Re: Restful Service Versioning
>>
>> Thanks all of you for the pointers.
>>
>> Petr,
>> Can you please elaborate on what "content negotiation" means in this
>> context
>>
>> Thank you,
>> Suchitha
>>
>> -----Original Message-----
>> From: Petr Jurák [mailto:petr.jurak_at_gmail.com]
>> Sent: Thursday, May 05, 2011 12:01 PM
>> To: users_at_jersey.java.net
>> Subject: [Jersey] Re: Restful Service Versioning
>>
>> IMHO version in URI isn't good idea. This will mess up resources and break
>> permalinks. I think it's better to use content negotiation and some custom
>> media types.
>> Therefore I agree with Ryan.
>>
>> Regards,
>> Petr
>>
>> -----Original Message-----
>> From: Ryan [mailto:zzantozz_at_gmail.com]
>> Sent: Thursday, May 05, 2011 6:47 PM
>> To: users_at_jersey.java.net
>> Subject: [Jersey] Re: Restful Service Versioning
>>
>> This is a widely- and hotly-debated topic that has been done over many times
>> before. Check http://www.google.com/search?q=rest+versioning. A strong
>> argument against embedding versions in the URI is that it implies v1 and v2
>> of some thing are in fact two different things because they have two
>> different identifiers (URIs).
>>
>> On Thu, May 05, 2011 at 10:59:27AM -0400, Gary Moore wrote:
>>> +1 to versions in the URL. You can also use a request header value.
>>>
>>> Using the URL scheme with Jersey, it would be as easy as writing a new
>>> Resource class(s) with new endpoints. For example:
>>>
>>> @Path("/v1/myresource")
>>> public class MyResource
>>>
>>> @Path("/v2/myresource")
>>> public class MyResourceV2
>>>
>>> You can use url re-write rules so that legacy clients (that didn't
>>> have the version in the URL) would get routed to v1.
>>>
>>> Another solution, if you didn't want to proliferate your resource
>>> classes, could be:
>>>
>>> @Path("/{apiVersion}/myresource")
>>> public class MyResource
>>>
>>> Then your methods could interpret the apiVerison and act accordingly.
>>>
>>> Gary
>>>
>>> On Wed, May 4, 2011 at 9:12 PM, Jason Erickson
>>> <jason_at_jasonerickson.com>
>> wrote:
>>>> From a URL perspective, I have seen the version included in the
>>>> path. For
>>>> example: http://domain.com/ws/v1/people and
>>>> http://domain.com/ws/v2/people would point to two versions of the API.
>>>> However, that is just a small part of the problem. I would also be
>>>> very interested in best practices used by others who are using
>>>> Jersey and JAXB to implement the versioning scheme described above
>>>> (or any other version scheme that people use to solve this problem).
>>>> On May 4, 2011, at 5:36 PM, "Suchitha Koneru (sukoneru)"
>>>> <sukoneru_at_cisco.com> wrote:
>>>>
>>>> Hello Jersey Users,
>>>>
>>>>
>>>>
>>>> What are the best practices for versioning of Restful services.
>>>> Our application will have multiple versions of Restful services
>>>> being published over a period of time. I could not find a
>>>> standardized approach which W3C recommends for versioning of services.
>>>>
>>>>
>>>>
>>>> Thanks,
>>>>
>>>> Suchitha
>>>
>>>
>>>
>>> --
>>> Gary Moore
>>> http://www.gmoore.net
>>
>>
>>