URI versioning

[torcud]

I am trying to implement the API best practice of versioning my URIs.
As such I want them to look like this /v1/users/{key}. The problem i
am running into is that the only way i can get this to work is by
building a V1 endpoint and throwing all of my functions in there. This
could get ugly fast. i tried to do a cfinclude of some functions but
that didn't work.

Is there a to implement this URI naming scheme in Mach II 1.9?

Any info would help!

Jean

[Rachel Lehman]

So Jean and I work together and just discussed this. We think we have a workable solution but we wanted to share to see if anyone else has feedback or ideas for a better solution.

Here's what we came up with:

• We want our URLs to be formatted as /v1/person/{1234}, but our endpoints will be configured to accept /person/{1234}
• We will use URL rewriting to remove /v1/ from the path and append it as a query string. So /v1/person/{1234} becomes /person/{1234}?version=1 (or something like that)
• We will use a plugin or some other type of global framework construct (best solution TBD) to grab that version argument and route to the appropriate version of the API
• We are thinking that we might try using separate modules for each version of the API (we have not yet done much with modules so this will be a new venture for us)

Appreciate any thoughts anyone can share!

Thanks,

-Rachel

[Doug]

This is a good question. We subscribe to an arguably more "RESTful"
practice of not versioning in the URI. Instead, ask for a version in
the Accept header, and return the version in the Content-Type header.
Clients who don't request a certain version get the latest.

There's a good discussion of pros/cons here:
http://stackoverflow.com/questions/389169/best-practices-for-api-versioning

If you really want to put a version in the URI, you can use URI
rewriting to redirect from a non-versioned URI to the latest. I would
recommend that if you really must go with versioning in the URI, since
"Cool URIs don't change".

Thanks,

Doug

On Feb 28, 2:04 pm, Rachel Lehman <raeleh...@gmail.com> wrote:
> So Jean and I work together and just discussed this. We think we have a
> workable solution but we wanted to share to see if anyone else has feedback
> or ideas for a better solution.
> Here's what we came up with:
>

>    - We want our URLs to be formatted as /v1/person/{1234}, but our

>    endpoints will be configured to accept /person/{1234}

>    - We will use URL rewriting to remove /v1/ from the path and append it

>    as a query string. So /v1/person/{1234} becomes /person/{1234}?version=1
>    (or something like that)

>    - We will use a plugin or some other type of global framework construct

>    (best solution TBD) to grab that version argument and route to the
>    appropriate version of the API

>    - We are thinking that we might try using separate modules for each

[Jean Ducrot]

Thanks Doug. I agree that passing the api version in the query string of the URI is technically more "RESTful". However it's important to remember that Fielding wrote his paper 12 years ago and the state of the web today is very different. After doing much digging on the topic of URI versioning we decided to adopt the pragmatic approach presented by api business veteran Apigee ( http://blog.apigee.com/detail/restful_api_design_tips_for_versioning/ ). This was mainly to avoid what happened to Facebook when they were passing their version as an optional query string parameter and several API consuming clients broke upon upgrade to v2.

As far as designing a versioned API on top of MACH II, would it be worth creating a module for our API or each version of it? Beyond keeping things cleaner architecturally, what other benefits could we reap going that way? Do you know the impact it would have on memory?

Thanks again for sharing your insight on the topic.

Jean

[Doug]

I can understand why you'd go that route, many do. For clarification,
I recommended putting versions in "Accept" HTTP headers, not a query
string.

Our philosophy on the subject has been: changing the API should be
rare. Versioning shouldn't be necessary very often. If you're Facebook
or Salesforce it may make sense to go that route, but for most RESTful
URIs, I'd push for designing an API that shouldn't need to change.

Other thoughts on this:
http://stackoverflow.com/questions/2024600/rest-api-versioning-only-version-the-representation-not-the-resource-itself

Good discussion!

Doug

On Feb 29, 10:49 am, Jean Ducrot <tor...@gmail.com> wrote:
> Thanks Doug. I agree that passing the api version in the query string of
> the URI is technically more "RESTful". However it's important to remember
> that Fielding wrote his paper 12 years ago and the state of the web today
> is very different. After doing much digging on the topic of URI versioning
> we decided to adopt the pragmatic approach presented by api business
> veteran Apigee (http://blog.apigee.com/detail/restful_api_design_tips_for_versioning/).
> This was mainly to avoid what happened to Facebook when they
> were passing their version as an optional query string parameter and
> several API consuming clients broke upon upgrade to v2.
>
> As far as designing a versioned API on top of MACH II, would it be worth
> creating a module for our API or each version of it? Beyond keeping things
> cleaner architecturally, what other benefits could we reap going that way?
> Do you know the impact it would have on memory?
>
> Thanks again for sharing your insight on the topic.
>
> Jean
>
>
>
>
>
>
>
> On Tuesday, February 28, 2012 3:20:36 PM UTC-5, Doug wrote:
>
> > This is a good question. We subscribe to an arguably more "RESTful"
> > practice of not versioning in the URI. Instead, ask for a version in
> > the Accept header, and return the version in the Content-Type header.
> > Clients who don't request a certain version get the latest.
>
> > There's a good discussion of pros/cons here:

> >http://stackoverflow.com/questions/389169/best-practices-for-api-vers...

> >http://stackoverflow.com/questions/389169/best-practices-for-api-vers...

> >http://stackoverflow.com/questions/389169/best-practices-for-api-vers...

> ...
>
> read more »

[Jean Ducrot]

Thanks Doug for the info we'll definitely look more into the header route for passing the request version information.

On Tuesday, February 28, 2012 3:20:36 PM UTC-5, Doug wrote: