Versioning with Apache Wink

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Versioning with Apache Wink

Darin Amos
Hello,

I have been reviewing the best way to version my ApacheWink API’s for the last few weeks and I think this is an area where Jax-RS falls a little short.

I understand that Apache Wink (Jax-RS) allows two mechanisms to version API’s that are popular.
        - URI path: GET /api/product —>  GET /api/product-v2 (or /api/product/v2 etc…)
        - Accept Header:   GET /api/product  header: Accept:application/v2+json

While these both make sense, there are also both a little limiting. I don’t want to get into a debate about API design, but for me using a query parameter or a custom header is a better option.

I am curious if anyone has done versioning with Apache wink with a query parameter or a custom header in the past. It looks like Apache Wink would be easy to extend to allow this if the filterDispatchMethods method was declared as public in the ResourceRegistry.

Has anyone else tried something like this in the past?

Thanks

Darin
Reply | Threaded
Open this post in threaded view
|

Re: Versioning with Apache Wink

Brian Laskey
Hello Darin,

I can't give you a concrete answer, but wanted to reply. We are also facing this question. We have made our new version yet, but I had been thinking of following the media-type extension strategy as described in this article, as it seemed like a clean way to achieve and should be relatively easier on the consumers of our API I would think.
http://www.narwhl.com/2015/03/the-ultimate-solution-to-versioning-rest-apis-content-negotiation/

Which seems like the second approach you mention, using the Accept header.

I would be curious to hear how other teams have done it, and in particular if any approach were easier for wink implementations in particular.


On Mon, Jan 11, 2016 at 12:12 PM, Darin Amos <[hidden email]> wrote:
Hello,

I have been reviewing the best way to version my ApacheWink API’s for the last few weeks and I think this is an area where Jax-RS falls a little short.

I understand that Apache Wink (Jax-RS) allows two mechanisms to version API’s that are popular.
        - URI path: GET /api/product —>  GET /api/product-v2 (or /api/product/v2 etc…)
        - Accept Header:   GET /api/product  header: Accept:application/v2+json

While these both make sense, there are also both a little limiting. I don’t want to get into a debate about API design, but for me using a query parameter or a custom header is a better option.

I am curious if anyone has done versioning with Apache wink with a query parameter or a custom header in the past. It looks like Apache Wink would be easy to extend to allow this if the filterDispatchMethods method was declared as public in the ResourceRegistry.

Has anyone else tried something like this in the past?

Thanks

Darin

Reply | Threaded
Open this post in threaded view
|

Re: Versioning with Apache Wink

Darin Amos
Thanks for the input Brian,

It is one of the better ways and we might ultimately do this; however, I am personally not a big fan of using the Accept header because it could cause confusion if you want to version a service that only posts content and doesn’t return content. You would have to use the Content-Type header instead of the Accept header. This is why a custom version header would be a little cleaner. I like to design clean interfaces.

In theory you could have a service that doesn’t accept or return any content, it is hard to imagine something like this, but not all REST applications are simple and can be implemented like a REST purist would like.

Cheers

Darin



On Jan 11, 2016, at 12:19 PM, Brian Laskey <[hidden email]> wrote:

Hello Darin,

I can't give you a concrete answer, but wanted to reply. We are also facing this question. We have made our new version yet, but I had been thinking of following the media-type extension strategy as described in this article, as it seemed like a clean way to achieve and should be relatively easier on the consumers of our API I would think.
http://www.narwhl.com/2015/03/the-ultimate-solution-to-versioning-rest-apis-content-negotiation/

Which seems like the second approach you mention, using the Accept header.

I would be curious to hear how other teams have done it, and in particular if any approach were easier for wink implementations in particular.


On Mon, Jan 11, 2016 at 12:12 PM, Darin Amos <[hidden email]> wrote:
Hello,

I have been reviewing the best way to version my ApacheWink API’s for the last few weeks and I think this is an area where Jax-RS falls a little short.

I understand that Apache Wink (Jax-RS) allows two mechanisms to version API’s that are popular.
        - URI path: GET /api/product —>  GET /api/product-v2 (or /api/product/v2 etc…)
        - Accept Header:   GET /api/product  header: Accept:application/v2+json

While these both make sense, there are also both a little limiting. I don’t want to get into a debate about API design, but for me using a query parameter or a custom header is a better option.

I am curious if anyone has done versioning with Apache wink with a query parameter or a custom header in the past. It looks like Apache Wink would be easy to extend to allow this if the filterDispatchMethods method was declared as public in the ResourceRegistry.

Has anyone else tried something like this in the past?

Thanks

Darin