Re: API versioning

Hiya,

> To be honest I'm still not sure how this would be handled if two clients
> diverge in their understanding of the same resource.

I think there needs to be made some distinctions between a shared
understanding of models and a shared understanding of a resource in that
model. Very often the model stays the same, and so the entities of that
models shouldn't change, or at best, provide a framework for dealing with
small changes (like backwards compatibility of models).

What many confuse as an API change in terms of REST is really a model
change, not a change to the language itself, which is REST. Even if the
internal representation of a resource changes, its place in the model most
often does not, and neither does the interface. True REST (TM) is
representational through hyperlinks, and applications should be guided
through the model rather than having knowledge of it, at least in an ideal
world (but people tend to think the overhead is too great for the world of
computing to deal with). There's no point in changing the interface nor the
model if only representation changes. That is probably better dealt with
through content negotiation, or, at worst, inside the representation level
itself.

What's being stressed here is that the separation of interface, model and
internal representation most often do not require versioning, at least not
on the model and interface level. So;

   /user/johnson
   /invoice/1023
   /process/345/participants

These are URIs that probably don't change with "versions". So why version
them at this level? The model is probably fine, only semantics and
representations change, so why not deal with it at that level instead?

Hope that makes sense. :) If not, gives us some examples of a change from
one version to the next, and let's talk about various ways to deal with the
changes in question.


Regards,

Alex








On Wed, Jan 9, 2013 at 4:25 PM, Keith Hassen <[email protected]> wrote:

> **
>
>
> First of all, thanks for the replies and perspective on REST.
>
> Backing up to the original question it seems like your particular take on
> it is that there's no need to version URIs or the resource representations
> provided that a cautious approach is taken to resource evolution.
>
> To be honest I'm still not sure how this would be handled if two clients
> diverge in their understanding of the same resource.  Perhaps that
> divergence leads us to different concepts and thus different resources and
> I've just been thinking about the problem incorrectly. :)
>
> Back to your most recent response...
>
> This seems to be a recommended practice that I've encountered in
>
> reading about RESTful implementations.
>
>
>
> Perfectly good HTTP API practice; REST, not so much.  The point of
> media types is to provide loose coupling based on shared understanding
> of how the representation is to be decoded.
>
>
> I think I'm actually talking about loose coupling, but this area seems a
> little fuzzy.  Comprehensive coverage of media type seems to be missing
> from Fielding's dissertation.  The media type I specified was definitely
> too specific (vnd.example.com might be a better choice rather than
> vnd.example.com.order, the latter effectively binding the media type to the
> representation and starts smelling like RPC modelling rather than the loose
> coupling promoted by the RESTful style).
>
> So how tight should this coupling be?  And what about versioning?  I'm
> tempted to say that if versioning is required, do so in the URi rather than
> the media type.  The media type seems to be more of an
> assertion/expectation regarding application context rather than a
> specification of the resource.
>
> It's amazing (or maybe not at all amazing) how divided this subject
> appears to be on the web.  This:
> http://www.informit.com/articles/article.aspx?p=1566460 is a pretty
> typical example.
>
> Thanks again for the feedback.
>
> K
>
>
> On 2013-01-08, at 12:57 AM, Eric J. Bowman wrote:
>
> Keith Hassen wrote:
>
>
> This seems to be a recommended practice that I've encountered in
>
> reading about RESTful implementations.
>
>
>
> Perfectly good HTTP API practice; REST, not so much.  The point of
> media types is to provide loose coupling based on shared understanding
> of how the representation is to be decoded.  Not tight coupling based
> on interpreting the content of the representation.  I've never seen an
> order API that couldn't be represented as HTML; despite any number of
> variations on this theme (or versions within), the media type doesn't
> vary between more order APIs on the Web than I can count.
>
> REST has no notion of resource "type" let alone of exposing same on the
> wire, so I've never understood why this solution is so prevalent in REST
> discussions.  Just media types, which are agnostic as to what "type" of
> resource is being represented (with rare exceptions as parameters).
>
>
> Anything else is up to the user-agent to work out.  This is actually
>
> easier for m2m than h2m; a v1 m2m client should already ignore any
>
> hypertext it doesn't understand, rolling out v2 can then re-use any
>
> non-deprecated bits of the API already present plus the new stuff,
>
> and ignore the deprecated stuff.  Can't it?
>
>
> Not always, at least not in my experience. :)  I have found that
>
> while breaking changes don't happen often, they *do* happen.  Add to
>
> this the possibility of different types of API consumers that start
>
> off implementing your APIs the same way, but slowly (or rapidly!)
>
> diverge over time.  In some cases new resources (and thus new URIs)
>
> will suffice, but in other cases what we are doing is very
>
> specifically *evolving* the resource representation to accommodate
>
> new requirements.
>
>
>
> Then design for graceful degradation (or progressive enhancement) using
> client-side feature detection.  Just saying there's no need to swing
> the conneg hammer to turn this particular screw.
>
> -Eric
>
>
>  
>



-- 
 Project Wrangler, SOA, Information Alchemist, UX, RESTafarian, Topic Maps
--- http://shelter.nu/blog/ ----------------------------------------------
------------------ http://www.google.com/profiles/alexander.johannesen ---