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-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 <[email protected]> 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 > > 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 > > > > > > > > > > > > > > > > On Tuesday, February 28, 2012 11:39:06 AM UTC-5, torcud wrote: > > > > > 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 > > On Tuesday, February 28, 2012 11:39:06 AM UTC-5, torcud wrote: > > > > > 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 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-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 <[email protected]> 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 > > 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 > > > > > > > > > > > > > > > > On Tuesday, February 28, 2012 11:39:06 AM UTC-5, torcud wrote: > > > > > 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 > > On Tuesday, February 28, 2012 11:39:06 AM UTC-5, torcud wrote: > > > > > 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 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-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 <[email protected]> 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 > > 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 > > > > > > > > > > > > > > > > On Tuesday, February 28, 2012 11:39:06 AM UTC-5, torcud wrote: > > > > > 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 > > On Tuesday, February 28, 2012 11:39:06 AM UTC-5, torcud wrote: > > > > > 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 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-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 <[email protected]> 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 > > 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 > > > > > > > > > > > > > > > > On Tuesday, February 28, 2012 11:39:06 AM UTC-5, torcud wrote: > > > > > 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 > > On Tuesday, February 28, 2012 11:39:06 AM UTC-5, torcud wrote: > > > > > 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 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-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 <[email protected]> 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 > > 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 > > > > > > > > > > > > > > > > On Tuesday, February 28, 2012 11:39:06 AM UTC-5, torcud wrote: > > > > > 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 > > On Tuesday, February 28, 2012 11:39:06 AM UTC-5, torcud wrote: > > > > > 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 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-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 <[email protected]> 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 > > 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 > > > > > > > > > > > > > > > > On Tuesday, February 28, 2012 11:39:06 AM UTC-5, torcud wrote: > > > > > 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 > > On Tuesday, February 28, 2012 11:39:06 AM UTC-5, torcud wrote: > > > > > 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 -- To post to this group, send email to [email protected] For more options and to unsubscribe, visit this group at http://groups.google.com/group/mach-ii-for-coldfusion?hl=en SVN: http://svn.mach-ii.com/machii/ Wiki / Documentation / Tickets: http://trac.mach-ii.com/machii/
