librelist archives

« back to archive

Versioning

Versioning

From:
Martin Wawrusch
Date:
2012-03-16 @ 07:30
Hi Steve,

just re read this on your blog:

Since I've posted this, I've refined a few of my positions on things.
Everyone learns and grows, and while I still stand by most of what I said,
I specifically don't agree that versioning the media type is how to
properly version APIs. Hypermedia APIs should not actually use explicit
versioning, but I'd rather see a version in the URI with HATEOAS than no
HATEOAS and versioned media types. I've been meaning to update this post
and write more, but alas, my work on Get some REST <http://getsomere.st/> has
taken priority. I don't have a HN account, so feel free to email
me<steve@steveklabnik.com> with
any thoughts or questions!

Not sure what your stand is right now, but I am strongly opposed to
versioning in the URL. This is imho one of the prime reasons why the whole
API ecosystem is so fucked up right now (even my own APIs...) The key seems
to be to use the ;version approach as linked to in your article here:
http://www.informit.com/articles/article.aspx?p=1566460

So basically it should work like this:

Only one URL per entity in your graph
A request without version returns the latest
A request with a specific version request returns that.
A request to an entity that has been renamed returns a permanent redirect
A request to an entity with a specific version that has been renamed after
that version still returns the object.

The clients really need to be smart about this. Basically we are dealing
with the same problem Object Relational Mappers have dealt for 15 years,
but on Internet scale. Lock in a client view model against a specific
version of the API, and let the API client and server figure out how to
deal with the mapping regardless how the server changed in the meantime. I
think I am going to write a sample to test this out.

Thoughts?

BTW, some more ideas for the site:
* List of all people who subscribed, plus profile links (I want to connect
to everyone who has a strong interest in this.
* List of all people in the REST space, authors, blogs, books.
* Add API checklists, detailing what specific parts of an API need to do
(for example return a location header, ...)
* Add sample scenarios how to model business problems in an API well.
Classic examples: transactions like you described in your blog post (I use
the same model.)



-- 
Martin Wawrusch

Re: [designinghypermediaapis] Versioning

From:
Nicholas Whittier
Date:
2012-03-16 @ 13:04
Martin,

These are great recommendations.  I wanted to share some thoughts:


> BTW, some more ideas for the site:
> * List of all people who subscribed, plus profile links (I want to connect
> to everyone who has a strong interest in this.
>

I like this, but maybe with opt-in to support users who want to lurk or
just read?


> * List of all people in the REST space, authors, blogs, books.
>

Related (though distinct), I was thinking about a bibliography of your
sources cited at a global level; I'm still trying to figure out a way to
make it approachable, and not just an enormous link list.


> * Add API checklists, detailing what specific parts of an API need to do
> (for example return a location header, ...)
>

+1


> * Add sample scenarios how to model business problems in an API well.
> Classic examples: transactions like you described in your blog post (I use
> the same model.)
>

+1


-- Nicholas

Re: [designinghypermediaapis] Versioning

From:
Steve Klabnik
Date:
2012-03-16 @ 13:05
Hey Martin,

Two things: 1, I changed the name of the list, and forgot to delete
this one. It's supposed to be hypermedia@ libralist.com

Secondly, we started a thread there,

http://librelist.com/browser//hypermedia/2012/3/11/versioning-is-an-anti-pattern-more-info/

Basically, I don't think versioning is a good idea, period. That said,
I think that URLS + hypermedia is a better way to transition to the
eventual right answer.

I plan on writing more when I have the time, but I'm at a conference
and I'm presenting in two hours. ;)

-Steve

On Fri, Mar 16, 2012 at 1:30 AM, Martin Wawrusch <martin@wawrusch.com> wrote:
> Hi Steve,
>
> just re read this on your blog:
>
> Since I've posted this, I've refined a few of my positions on things.
> Everyone learns and grows, and while I still stand by most of what I said, I
> specifically don't agree that versioning the media type is how to properly
> version APIs. Hypermedia APIs should not actually use explicit versioning,
> but I'd rather see a version in the URI with HATEOAS than no HATEOAS and
> versioned media types. I've been meaning to update this post and write more,
> but alas, my work on Get some REST has taken priority. I don't have a HN
> account, so feel free to email me with any thoughts or questions!
>
> Not sure what your stand is right now, but I am strongly opposed to
> versioning in the URL. This is imho one of the prime reasons why the whole
> API ecosystem is so fucked up right now (even my own APIs...) The key seems
> to be to use the ;version approach as linked to in your article
> here: http://www.informit.com/articles/article.aspx?p=1566460
>
> So basically it should work like this:
>
> Only one URL per entity in your graph
> A request without version returns the latest
> A request with a specific version request returns that.
> A request to an entity that has been renamed returns a permanent redirect
> A request to an entity with a specific version that has been renamed after
> that version still returns the object.
>
> The clients really need to be smart about this. Basically we are dealing
> with the same problem Object Relational Mappers have dealt for 15 years, but
> on Internet scale. Lock in a client view model against a specific version of
> the API, and let the API client and server figure out how to deal with the
> mapping regardless how the server changed in the meantime. I think I am
> going to write a sample to test this out.
>
> Thoughts?
>
> BTW, some more ideas for the site:
> * List of all people who subscribed, plus profile links (I want to connect
> to everyone who has a strong interest in this.
> * List of all people in the REST space, authors, blogs, books.
> * Add API checklists, detailing what specific parts of an API need to do
> (for example return a location header, ...)
> * Add sample scenarios how to model business problems in an API well.
> Classic examples: transactions like you described in your blog post (I use
> the same model.)
>
>
>
> --
> Martin Wawrusch
>
>
>
>

Re: [designinghypermediaapis] Versioning

From:
Martin Wawrusch
Date:
2012-03-16 @ 13:39
K thx, I subscribed to the new one. Have a great talk, lets discuss this
later.

On Fri, Mar 16, 2012 at 6:05 AM, Steve Klabnik <steve@steveklabnik.com>wrote:

> Hey Martin,
>
> Two things: 1, I changed the name of the list, and forgot to delete
> this one. It's supposed to be hypermedia@ libralist.com
>
> Secondly, we started a thread there,
>
> 
http://librelist.com/browser//hypermedia/2012/3/11/versioning-is-an-anti-pattern-more-info/
>
> Basically, I don't think versioning is a good idea, period. That said,
> I think that URLS + hypermedia is a better way to transition to the
> eventual right answer.
>
> I plan on writing more when I have the time, but I'm at a conference
> and I'm presenting in two hours. ;)
>
> -Steve
>
> On Fri, Mar 16, 2012 at 1:30 AM, Martin Wawrusch <martin@wawrusch.com>
> wrote:
> > Hi Steve,
> >
> > just re read this on your blog:
> >
> > Since I've posted this, I've refined a few of my positions on things.
> > Everyone learns and grows, and while I still stand by most of what I
> said, I
> > specifically don't agree that versioning the media type is how to
> properly
> > version APIs. Hypermedia APIs should not actually use explicit
> versioning,
> > but I'd rather see a version in the URI with HATEOAS than no HATEOAS and
> > versioned media types. I've been meaning to update this post and write
> more,
> > but alas, my work on Get some REST has taken priority. I don't have a HN
> > account, so feel free to email me with any thoughts or questions!
> >
> > Not sure what your stand is right now, but I am strongly opposed to
> > versioning in the URL. This is imho one of the prime reasons why the
> whole
> > API ecosystem is so fucked up right now (even my own APIs...) The key
> seems
> > to be to use the ;version approach as linked to in your article
> > here: http://www.informit.com/articles/article.aspx?p=1566460
> >
> > So basically it should work like this:
> >
> > Only one URL per entity in your graph
> > A request without version returns the latest
> > A request with a specific version request returns that.
> > A request to an entity that has been renamed returns a permanent redirect
> > A request to an entity with a specific version that has been renamed
> after
> > that version still returns the object.
> >
> > The clients really need to be smart about this. Basically we are dealing
> > with the same problem Object Relational Mappers have dealt for 15 years,
> but
> > on Internet scale. Lock in a client view model against a specific
> version of
> > the API, and let the API client and server figure out how to deal with
> the
> > mapping regardless how the server changed in the meantime. I think I am
> > going to write a sample to test this out.
> >
> > Thoughts?
> >
> > BTW, some more ideas for the site:
> > * List of all people who subscribed, plus profile links (I want to
> connect
> > to everyone who has a strong interest in this.
> > * List of all people in the REST space, authors, blogs, books.
> > * Add API checklists, detailing what specific parts of an API need to do
> > (for example return a location header, ...)
> > * Add sample scenarios how to model business problems in an API well.
> > Classic examples: transactions like you described in your blog post (I
> use
> > the same model.)
> >
> >
> >
> > --
> > Martin Wawrusch
> >
> >
> >
> >
>