On API Versioning

Justin Harris jharris at redhat.com
Tue Apr 27 15:06:03 UTC 2010


----- "Jesus Rodriguez" <jesusr at redhat.com> wrote:

> On Tue, Apr 27, 2010 at 10:26:40AM -0300, Devan Goodwin wrote:
> > The v2 in the URL is gross but it would help with keeping the code
> > reusable I think as we could fork to different resources inheriting
> > from common parent classes. Not sure if we could do the same with
> > media type checking, at least not as easily.
> > 
> > Would the plain URL always be the latest and greatest with vX for
> > those who want stability? Or is it no vX assumed to be v1 and we
> > increment for all future releases.
> >
> 
> based on bryan's email 'no v implies v1'. 
> 
> What will our deprecation policy be? mark it deprecated and
> it gets removed in the next version?
> 
> Also, having the v2 in front of the resources makes it a little
> harder
> to reuse code, but how many versions will we have? 2? 3? n?
> I'm thinking no more than 3, personally 2 would be great.
> 
> If the v2 was after the resource we could actually reuse the
> same Resouce classes, i.e.
> 
> GET /candlein/owner/v2/
> 
> This would simply be:
> 
>    @GET
>    @Path("/v2")
>    public Owner getOwnerNew(...)
> 
> With the v2 in front of the Resource we'll have to create a new
> set of resource classes.

I would be very careful about this.  Putting the version higher up conflicts with the REST semantics.  I know the intent here, but convention would imply that that GET /candlepin/owners/v2 would be getting an owner named "v2".

So that's a -1 from me. :)

> 
> jesus
> 
> -- 
> jesus m. rodriguez          | jesusr at redhat.com
> principal software engineer | irc: zeus
> red hat systems management  | 919.754.4413 (w)
> rhce # 805008586930012      | 919.623.0080 (c)
> +---------------------------------------------+
> |   "Those who cannot remember the past       |
> |    are condemned to repeat it."             |
> |                        -- George Santayana  |
> +---------------------------------------------+
> 
> _______________________________________________
> candlepin mailing list
> candlepin at lists.fedorahosted.org
> https://fedorahosted.org/mailman/listinfo/candlepin



More information about the candlepin mailing list