Best practices for API versioning

Question

Are there any known how-tos or best practices for web service REST API versioning   I have noticed that AWS does versioning by the URL of the endpoint  Is this the only way or are there other ways to accomplish the same goal  If there are multiple ways  what are the merits of each way

User · Answer

There are a few places you can do versioning in a REST API:

As noted, in the URI. This can be tractable and even esthetically pleasing if redirects and the like are used well.
In the Accepts: header, so the version is in the filetype. Like 'mp3' vs 'mp4'. This will also work, though IMO it works a bit less nicely than...
In the resource itself. Many file formats have their version numbers embedded in them, typically in the header; this allows newer software to 'just work' by understanding all existing versions of the filetype while older software can punt if an unsupported (newer) version is specified. In the context of a REST API, it means that your URIs never have to change, just your response to the particular version of data you were handed.

I can see reasons to use all three approaches:

if you like doing 'clean sweep' new APIs, or for major version changes where you want such an approach.
if you want the client to know before it does a PUT/POST whether it's going to work or not.
if it's okay if the client has to do its PUT/POST to find out if it's going to work.

User · Answer

We found it practical and useful to put the version in the URL   It makes it easy to tell what you re using at a glance   We do alias  foo to  foo  latest versions  for ease of use  shorter   cleaner URLs  etc  as the accepted answer suggests   Keeping backwards compatibility forever is often cost-prohibitive and or very difficult   We prefer to give advanced notice of deprecation  redirects like suggested here  docs  and other mechanisms

User · Answer

Put your version in the URI   One version of an API will not always support the types from another  so the argument that resources are merely migrated from one version to another is just plain wrong   It s not the same as switching format from XML to JSON   The types may not exist  or they may have changed semantically   Versions are part of the resource address   You re routing from one API to another   It s not RESTful to hide addressing in the header

User · Answer

This is a good and a tricky question  The topic of URI design is at the same time the most prominent part of a REST API and  therefore  a potentially long-term commitment towards the users of that API   Since evolution of an application and  to a lesser extent  its API is a fact of life and that it s even similar to the evolution of a seemingly complex product like a programming language  the URI design should have less natural constraints and it should be preserved over time  The longer the application s and API s lifespan  the greater the commitment to the users of the application and API   On the other hand  another fact of life is that it is hard to foresee all the resources and their aspects that would be consumed through the API  Luckily  it is not necessary to design the entire API which will be used until Apocalypse  It is sufficient to correctly define all the resource end-points and the addressing scheme of every resource and resource instance   Over time you may need to add new resources and new attributes to each particular resource  but the method that API users follow to access a particular resources should not change once a resource addressing scheme becomes public and therefore final   This method applies to HTTP verb semantics  e g  PUT should always update replace  and HTTP status codes that are supported in earlier API versions  they should continue to work so that API clients that have worked without human intervention should be able to continue to work like that    Furthermore  since embedding of API version into the URI would disrupt the concept of hypermedia as the engine of application state  stated in Roy T  Fieldings PhD dissertation  by having a resource address URI that would change over time  I would conclude that API versions should not be kept in resource URIs for a long time meaning that resource URIs that API users can depend on should be permalinks   Sure  it is possible to embed API version in base URI but only for reasonable and restricted uses like debugging a API client that works with the the new API version  Such versioned APIs should be time-limited and available to limited groups of API users  like during closed betas  only  Otherwise  you commit yourself where you shouldn t   A couple of thoughts regarding maintenance of API versions that have expiration date on them  All programming platforms languages commonly used to implement web services  Java   NET  PHP  Perl  Rails  etc   allow easy binding of web service end-point s  to a base URI  This way it s easy to gather and keep a collection of files classes methods separate across different API versions    From the API users POV  it s also easier to work with and bind to a particular API version when it s this obvious but only for limited time  i e  during development   From the API maintainer s POV  it s easier to maintain different API versions in parallel by using source control systems that predominantly work on files as the smallest unit of  source code  versioning   However  with API versions clearly visible in URI there s a caveat  one might also object this approach since API history becomes visible aparent in the URI design and therefore is prone to changes over time which goes against the guidelines of REST  I agree   The way to go around this reasonable objection  is to implement the latest API version under versionless API base URI  In this case  API client developers can choose to either    develop against the latest one  committing themselves to maintain the application protecting it from eventual API changes that might break their badly designed API client   bind to a specific version of the API  which becomes apparent  but only for a limited time   For example  if API v3 0 is the latest API version  the following two should be aliases  i e  behave identically to all API requests     http   shonzilla api customers 1234 http   shonzilla api v3 0 customers 1234 http   shonzilla api v3 customers 1234   In addition  API clients that still try to point to the old API should be informed to use the latest previous API version  if the API version they re using is obsolete or not supported anymore  So accessing any of the obsolete URIs like these    http   shonzilla api v2 2 customers 1234 http   shonzilla api v2 0 customers 1234 http   shonzilla api v2 customers 1234 http   shonzilla api v1 1 customers 1234 http   shonzilla api v1 customers 1234   should return any of the 30x HTTP status codes that indicate redirection that are used in conjunction with Location HTTP header that redirects to the appropriate version of resource URI which remain to be this one    http   shonzilla api customers 1234   There are at least two redirection HTTP status codes that are appropriate for API versioning scenarios    301 Moved permanently indicating that the resource with a requested URI is moved permanently to another URI  which should be a resource instance permalink that does not contain API version info   This status code can be used to indicate an obsolete unsupported API version  informing API client that a versioned resource URI been replaced by a resource permalink  302 Found indicating that the requested resource temporarily is located at another location  while requested URI may still supported  This status code may be useful when the version-less URIs are temporarily unavailable and that a request should be repeated using the redirection address  e g  pointing to the URI with APi version embedded  and we want to tell clients to keep using it  i e  the permalinks   other scenarios can be found in Redirection 3xx chapter of HTTP 1 1 specification

User · Answer

Versioning your REST API is analogous to the versioning of any other API  Minor changes can be done in place  major changes might require a whole new API  The easiest for you is to start from scratch every time  which is when putting the version in the URL makes most sense  If you want to make life easier for the client you try to maintain backwards compatibility  which you can do with deprecation  permanent redirect   resources in several versions etc  This is more fiddly and requires more effort  But it s also what REST encourages in  Cool URIs don t change     In the end it s just like any other API design  Weigh effort against client convenience  Consider adopting semantic versioning for your API  which makes it clear for your clients how backwards compatible your new version is

User · Answer

The URL should NOT contain the versions   The version has nothing to do with  idea  of the resource you are requesting   You should try to think of the URL as being a path to the concept you would like - not how you want the item returned    The version dictates the representation of the object  not the concept of the object   As other posters have said  you should be specifying the format  including version  in the request header   If you look at the full HTTP request for the URLs which have versions  it looks like this    BAD WAY TO DO IT    http   company com api v3 0 customer 123      gt  GET v3 0 customer 123 HTTP 1 1 Accept  application xml   lt      HTTP 1 1 200 OK Content-Type  application xml  lt customer version  3 0  gt     lt name gt Neil Armstrong lt  name gt   lt  customer gt    The header contains the line which contains the representation you are asking for   Accept  application xml      That is where the version should go   Everyone seems to gloss over the fact that you may want the same thing in different formats and that the client should be able ask for what it wants   In the above example  the client is asking for ANY XML representation of the resource - not really the true representation of what it wants   The server could  in theory  return something completely unrelated to the request as long as it was XML and it would have to be parsed to realize it is wrong   A better way is    GOOD WAY TO DO IT   http   company com api customer 123     gt  GET  customer 123 HTTP 1 1 Accept  application vnd company myapp customer-v3 xml   lt     HTTP 1 1 200 OK Content-Type  application vnd company myapp-v3 xml  lt customer gt     lt name gt Neil Armstrong lt  name gt   lt  customer gt    Further  lets say the clients think the XML is too verbose and now they want JSON instead   In the other examples you would have to have a new URL for the same customer  so you would end up with    BAD  http   company com api JSONv3 0 customers 123   or http   company com api v3 0 customers 123 format  JSON     or something similar     When in fact  every HTTP requests contains the format you are looking for    GOOD WAY TO DO IT      gt  GET  customer 123 HTTP 1 1 Accept  application vnd company myapp customer-v3 json   lt     HTTP 1 1 200 OK Content-Type  application vnd company myapp-v3 json    customer       name   Neil Armstrong       Using this method  you have much more freedom in design and are actually adhering to the original idea of REST   You can change versions without disrupting clients  or incrementally change clients as the APIs are changed   If you choose to stop supporting a representation  you can respond to the requests with HTTP status code or custom codes   The client can also verify the response is in the correct format  and validate the XML   There are many other advantages and I discuss some of them here on my blog    http   thereisnorightway blogspot com 2011 02 versioning-and-types-in-resthttp-api html  One last example to show how putting the version in the URL is bad   Lets say you want some piece of information inside the object  and you have versioned your various objects  customers are v3 0  orders are v2 0  and shipto object is v4 2    Here is the nasty URL you must supply in the client    Another reason why version in the URL sucks  http   company com api v3 0 customer 123 v2 0 orders 4321

User · Answer

I agree that versioning the resource representation better follows the REST approach   but  one big problem with custom MIME types  or MIME types that append a version parameter  is the poor support to write to Accept and Content-Type headers in HTML and JavaScript   For example  it is not possible IMO to POST with the following headers in HTML5 forms  in order to create a resource   Accept  application vnd company myapp-v3 json Content-Type  application vnd company myapp-v3 json    This is because the HTML5 enctype attribute is an enumeration  therefore anything other than the usual application x-www-formurlencoded  multipart form-data and text plain are invalid        nor am I sure it is supported across all browsers in HTML4  which has a more lax encytpe attribute  but would be a browser implementation issue as to whether the MIME type was forwarded   Because of this I now feel the most appropriate way to version is via the URI  but I accept that it is not the  correct  way

User · Answer

This is a good and a tricky question  The topic of URI design is at the same time the most prominent part of a REST API and  therefore  a potentially long-term commitment towards the users of that API   Since evolution of an application and  to a lesser extent  its API is a fact of life and that it s even similar to the evolution of a seemingly complex product like a programming language  the URI design should have less natural constraints and it should be preserved over time  The longer the application s and API s lifespan  the greater the commitment to the users of the application and API   On the other hand  another fact of life is that it is hard to foresee all the resources and their aspects that would be consumed through the API  Luckily  it is not necessary to design the entire API which will be used until Apocalypse  It is sufficient to correctly define all the resource end-points and the addressing scheme of every resource and resource instance   Over time you may need to add new resources and new attributes to each particular resource  but the method that API users follow to access a particular resources should not change once a resource addressing scheme becomes public and therefore final   This method applies to HTTP verb semantics  e g  PUT should always update replace  and HTTP status codes that are supported in earlier API versions  they should continue to work so that API clients that have worked without human intervention should be able to continue to work like that    Furthermore  since embedding of API version into the URI would disrupt the concept of hypermedia as the engine of application state  stated in Roy T  Fieldings PhD dissertation  by having a resource address URI that would change over time  I would conclude that API versions should not be kept in resource URIs for a long time meaning that resource URIs that API users can depend on should be permalinks   Sure  it is possible to embed API version in base URI but only for reasonable and restricted uses like debugging a API client that works with the the new API version  Such versioned APIs should be time-limited and available to limited groups of API users  like during closed betas  only  Otherwise  you commit yourself where you shouldn t   A couple of thoughts regarding maintenance of API versions that have expiration date on them  All programming platforms languages commonly used to implement web services  Java   NET  PHP  Perl  Rails  etc   allow easy binding of web service end-point s  to a base URI  This way it s easy to gather and keep a collection of files classes methods separate across different API versions    From the API users POV  it s also easier to work with and bind to a particular API version when it s this obvious but only for limited time  i e  during development   From the API maintainer s POV  it s easier to maintain different API versions in parallel by using source control systems that predominantly work on files as the smallest unit of  source code  versioning   However  with API versions clearly visible in URI there s a caveat  one might also object this approach since API history becomes visible aparent in the URI design and therefore is prone to changes over time which goes against the guidelines of REST  I agree   The way to go around this reasonable objection  is to implement the latest API version under versionless API base URI  In this case  API client developers can choose to either    develop against the latest one  committing themselves to maintain the application protecting it from eventual API changes that might break their badly designed API client   bind to a specific version of the API  which becomes apparent  but only for a limited time   For example  if API v3 0 is the latest API version  the following two should be aliases  i e  behave identically to all API requests     http   shonzilla api customers 1234 http   shonzilla api v3 0 customers 1234 http   shonzilla api v3 customers 1234   In addition  API clients that still try to point to the old API should be informed to use the latest previous API version  if the API version they re using is obsolete or not supported anymore  So accessing any of the obsolete URIs like these    http   shonzilla api v2 2 customers 1234 http   shonzilla api v2 0 customers 1234 http   shonzilla api v2 customers 1234 http   shonzilla api v1 1 customers 1234 http   shonzilla api v1 customers 1234   should return any of the 30x HTTP status codes that indicate redirection that are used in conjunction with Location HTTP header that redirects to the appropriate version of resource URI which remain to be this one    http   shonzilla api customers 1234   There are at least two redirection HTTP status codes that are appropriate for API versioning scenarios    301 Moved permanently indicating that the resource with a requested URI is moved permanently to another URI  which should be a resource instance permalink that does not contain API version info   This status code can be used to indicate an obsolete unsupported API version  informing API client that a versioned resource URI been replaced by a resource permalink  302 Found indicating that the requested resource temporarily is located at another location  while requested URI may still supported  This status code may be useful when the version-less URIs are temporarily unavailable and that a request should be repeated using the redirection address  e g  pointing to the URI with APi version embedded  and we want to tell clients to keep using it  i e  the permalinks   other scenarios can be found in Redirection 3xx chapter of HTTP 1 1 specification

User · Answer

There are a few places you can do versioning in a REST API:

As noted, in the URI. This can be tractable and even esthetically pleasing if redirects and the like are used well.
In the Accepts: header, so the version is in the filetype. Like 'mp3' vs 'mp4'. This will also work, though IMO it works a bit less nicely than...
In the resource itself. Many file formats have their version numbers embedded in them, typically in the header; this allows newer software to 'just work' by understanding all existing versions of the filetype while older software can punt if an unsupported (newer) version is specified. In the context of a REST API, it means that your URIs never have to change, just your response to the particular version of data you were handed.

I can see reasons to use all three approaches:

if you like doing 'clean sweep' new APIs, or for major version changes where you want such an approach.
if you want the client to know before it does a PUT/POST whether it's going to work or not.
if it's okay if the client has to do its PUT/POST to find out if it's going to work.

User · Answer

The URL should NOT contain the versions   The version has nothing to do with  idea  of the resource you are requesting   You should try to think of the URL as being a path to the concept you would like - not how you want the item returned    The version dictates the representation of the object  not the concept of the object   As other posters have said  you should be specifying the format  including version  in the request header   If you look at the full HTTP request for the URLs which have versions  it looks like this    BAD WAY TO DO IT    http   company com api v3 0 customer 123      gt  GET v3 0 customer 123 HTTP 1 1 Accept  application xml   lt      HTTP 1 1 200 OK Content-Type  application xml  lt customer version  3 0  gt     lt name gt Neil Armstrong lt  name gt   lt  customer gt    The header contains the line which contains the representation you are asking for   Accept  application xml      That is where the version should go   Everyone seems to gloss over the fact that you may want the same thing in different formats and that the client should be able ask for what it wants   In the above example  the client is asking for ANY XML representation of the resource - not really the true representation of what it wants   The server could  in theory  return something completely unrelated to the request as long as it was XML and it would have to be parsed to realize it is wrong   A better way is    GOOD WAY TO DO IT   http   company com api customer 123     gt  GET  customer 123 HTTP 1 1 Accept  application vnd company myapp customer-v3 xml   lt     HTTP 1 1 200 OK Content-Type  application vnd company myapp-v3 xml  lt customer gt     lt name gt Neil Armstrong lt  name gt   lt  customer gt    Further  lets say the clients think the XML is too verbose and now they want JSON instead   In the other examples you would have to have a new URL for the same customer  so you would end up with    BAD  http   company com api JSONv3 0 customers 123   or http   company com api v3 0 customers 123 format  JSON     or something similar     When in fact  every HTTP requests contains the format you are looking for    GOOD WAY TO DO IT      gt  GET  customer 123 HTTP 1 1 Accept  application vnd company myapp customer-v3 json   lt     HTTP 1 1 200 OK Content-Type  application vnd company myapp-v3 json    customer       name   Neil Armstrong       Using this method  you have much more freedom in design and are actually adhering to the original idea of REST   You can change versions without disrupting clients  or incrementally change clients as the APIs are changed   If you choose to stop supporting a representation  you can respond to the requests with HTTP status code or custom codes   The client can also verify the response is in the correct format  and validate the XML   There are many other advantages and I discuss some of them here on my blog    http   thereisnorightway blogspot com 2011 02 versioning-and-types-in-resthttp-api html  One last example to show how putting the version in the URL is bad   Lets say you want some piece of information inside the object  and you have versioned your various objects  customers are v3 0  orders are v2 0  and shipto object is v4 2    Here is the nasty URL you must supply in the client    Another reason why version in the URL sucks  http   company com api v3 0 customer 123 v2 0 orders 4321

User · Answer

This is a good and a tricky question  The topic of URI design is at the same time the most prominent part of a REST API and  therefore  a potentially long-term commitment towards the users of that API   Since evolution of an application and  to a lesser extent  its API is a fact of life and that it s even similar to the evolution of a seemingly complex product like a programming language  the URI design should have less natural constraints and it should be preserved over time  The longer the application s and API s lifespan  the greater the commitment to the users of the application and API   On the other hand  another fact of life is that it is hard to foresee all the resources and their aspects that would be consumed through the API  Luckily  it is not necessary to design the entire API which will be used until Apocalypse  It is sufficient to correctly define all the resource end-points and the addressing scheme of every resource and resource instance   Over time you may need to add new resources and new attributes to each particular resource  but the method that API users follow to access a particular resources should not change once a resource addressing scheme becomes public and therefore final   This method applies to HTTP verb semantics  e g  PUT should always update replace  and HTTP status codes that are supported in earlier API versions  they should continue to work so that API clients that have worked without human intervention should be able to continue to work like that    Furthermore  since embedding of API version into the URI would disrupt the concept of hypermedia as the engine of application state  stated in Roy T  Fieldings PhD dissertation  by having a resource address URI that would change over time  I would conclude that API versions should not be kept in resource URIs for a long time meaning that resource URIs that API users can depend on should be permalinks   Sure  it is possible to embed API version in base URI but only for reasonable and restricted uses like debugging a API client that works with the the new API version  Such versioned APIs should be time-limited and available to limited groups of API users  like during closed betas  only  Otherwise  you commit yourself where you shouldn t   A couple of thoughts regarding maintenance of API versions that have expiration date on them  All programming platforms languages commonly used to implement web services  Java   NET  PHP  Perl  Rails  etc   allow easy binding of web service end-point s  to a base URI  This way it s easy to gather and keep a collection of files classes methods separate across different API versions    From the API users POV  it s also easier to work with and bind to a particular API version when it s this obvious but only for limited time  i e  during development   From the API maintainer s POV  it s easier to maintain different API versions in parallel by using source control systems that predominantly work on files as the smallest unit of  source code  versioning   However  with API versions clearly visible in URI there s a caveat  one might also object this approach since API history becomes visible aparent in the URI design and therefore is prone to changes over time which goes against the guidelines of REST  I agree   The way to go around this reasonable objection  is to implement the latest API version under versionless API base URI  In this case  API client developers can choose to either    develop against the latest one  committing themselves to maintain the application protecting it from eventual API changes that might break their badly designed API client   bind to a specific version of the API  which becomes apparent  but only for a limited time   For example  if API v3 0 is the latest API version  the following two should be aliases  i e  behave identically to all API requests     http   shonzilla api customers 1234 http   shonzilla api v3 0 customers 1234 http   shonzilla api v3 customers 1234   In addition  API clients that still try to point to the old API should be informed to use the latest previous API version  if the API version they re using is obsolete or not supported anymore  So accessing any of the obsolete URIs like these    http   shonzilla api v2 2 customers 1234 http   shonzilla api v2 0 customers 1234 http   shonzilla api v2 customers 1234 http   shonzilla api v1 1 customers 1234 http   shonzilla api v1 customers 1234   should return any of the 30x HTTP status codes that indicate redirection that are used in conjunction with Location HTTP header that redirects to the appropriate version of resource URI which remain to be this one    http   shonzilla api customers 1234   There are at least two redirection HTTP status codes that are appropriate for API versioning scenarios    301 Moved permanently indicating that the resource with a requested URI is moved permanently to another URI  which should be a resource instance permalink that does not contain API version info   This status code can be used to indicate an obsolete unsupported API version  informing API client that a versioned resource URI been replaced by a resource permalink  302 Found indicating that the requested resource temporarily is located at another location  while requested URI may still supported  This status code may be useful when the version-less URIs are temporarily unavailable and that a request should be repeated using the redirection address  e g  pointing to the URI with APi version embedded  and we want to tell clients to keep using it  i e  the permalinks   other scenarios can be found in Redirection 3xx chapter of HTTP 1 1 specification

User · Answer

Put your version in the URI   One version of an API will not always support the types from another  so the argument that resources are merely migrated from one version to another is just plain wrong   It s not the same as switching format from XML to JSON   The types may not exist  or they may have changed semantically   Versions are part of the resource address   You re routing from one API to another   It s not RESTful to hide addressing in the header

User · Answer

Versioning your REST API is analogous to the versioning of any other API  Minor changes can be done in place  major changes might require a whole new API  The easiest for you is to start from scratch every time  which is when putting the version in the URL makes most sense  If you want to make life easier for the client you try to maintain backwards compatibility  which you can do with deprecation  permanent redirect   resources in several versions etc  This is more fiddly and requires more effort  But it s also what REST encourages in  Cool URIs don t change     In the end it s just like any other API design  Weigh effort against client convenience  Consider adopting semantic versioning for your API  which makes it clear for your clients how backwards compatible your new version is

User · Answer

I agree that versioning the resource representation better follows the REST approach   but  one big problem with custom MIME types  or MIME types that append a version parameter  is the poor support to write to Accept and Content-Type headers in HTML and JavaScript   For example  it is not possible IMO to POST with the following headers in HTML5 forms  in order to create a resource   Accept  application vnd company myapp-v3 json Content-Type  application vnd company myapp-v3 json    This is because the HTML5 enctype attribute is an enumeration  therefore anything other than the usual application x-www-formurlencoded  multipart form-data and text plain are invalid        nor am I sure it is supported across all browsers in HTML4  which has a more lax encytpe attribute  but would be a browser implementation issue as to whether the MIME type was forwarded   Because of this I now feel the most appropriate way to version is via the URI  but I accept that it is not the  correct  way

User · Answer

This is a good and a tricky question  The topic of URI design is at the same time the most prominent part of a REST API and  therefore  a potentially long-term commitment towards the users of that API   Since evolution of an application and  to a lesser extent  its API is a fact of life and that it s even similar to the evolution of a seemingly complex product like a programming language  the URI design should have less natural constraints and it should be preserved over time  The longer the application s and API s lifespan  the greater the commitment to the users of the application and API   On the other hand  another fact of life is that it is hard to foresee all the resources and their aspects that would be consumed through the API  Luckily  it is not necessary to design the entire API which will be used until Apocalypse  It is sufficient to correctly define all the resource end-points and the addressing scheme of every resource and resource instance   Over time you may need to add new resources and new attributes to each particular resource  but the method that API users follow to access a particular resources should not change once a resource addressing scheme becomes public and therefore final   This method applies to HTTP verb semantics  e g  PUT should always update replace  and HTTP status codes that are supported in earlier API versions  they should continue to work so that API clients that have worked without human intervention should be able to continue to work like that    Furthermore  since embedding of API version into the URI would disrupt the concept of hypermedia as the engine of application state  stated in Roy T  Fieldings PhD dissertation  by having a resource address URI that would change over time  I would conclude that API versions should not be kept in resource URIs for a long time meaning that resource URIs that API users can depend on should be permalinks   Sure  it is possible to embed API version in base URI but only for reasonable and restricted uses like debugging a API client that works with the the new API version  Such versioned APIs should be time-limited and available to limited groups of API users  like during closed betas  only  Otherwise  you commit yourself where you shouldn t   A couple of thoughts regarding maintenance of API versions that have expiration date on them  All programming platforms languages commonly used to implement web services  Java   NET  PHP  Perl  Rails  etc   allow easy binding of web service end-point s  to a base URI  This way it s easy to gather and keep a collection of files classes methods separate across different API versions    From the API users POV  it s also easier to work with and bind to a particular API version when it s this obvious but only for limited time  i e  during development   From the API maintainer s POV  it s easier to maintain different API versions in parallel by using source control systems that predominantly work on files as the smallest unit of  source code  versioning   However  with API versions clearly visible in URI there s a caveat  one might also object this approach since API history becomes visible aparent in the URI design and therefore is prone to changes over time which goes against the guidelines of REST  I agree   The way to go around this reasonable objection  is to implement the latest API version under versionless API base URI  In this case  API client developers can choose to either    develop against the latest one  committing themselves to maintain the application protecting it from eventual API changes that might break their badly designed API client   bind to a specific version of the API  which becomes apparent  but only for a limited time   For example  if API v3 0 is the latest API version  the following two should be aliases  i e  behave identically to all API requests     http   shonzilla api customers 1234 http   shonzilla api v3 0 customers 1234 http   shonzilla api v3 customers 1234   In addition  API clients that still try to point to the old API should be informed to use the latest previous API version  if the API version they re using is obsolete or not supported anymore  So accessing any of the obsolete URIs like these    http   shonzilla api v2 2 customers 1234 http   shonzilla api v2 0 customers 1234 http   shonzilla api v2 customers 1234 http   shonzilla api v1 1 customers 1234 http   shonzilla api v1 customers 1234   should return any of the 30x HTTP status codes that indicate redirection that are used in conjunction with Location HTTP header that redirects to the appropriate version of resource URI which remain to be this one    http   shonzilla api customers 1234   There are at least two redirection HTTP status codes that are appropriate for API versioning scenarios    301 Moved permanently indicating that the resource with a requested URI is moved permanently to another URI  which should be a resource instance permalink that does not contain API version info   This status code can be used to indicate an obsolete unsupported API version  informing API client that a versioned resource URI been replaced by a resource permalink  302 Found indicating that the requested resource temporarily is located at another location  while requested URI may still supported  This status code may be useful when the version-less URIs are temporarily unavailable and that a request should be repeated using the redirection address  e g  pointing to the URI with APi version embedded  and we want to tell clients to keep using it  i e  the permalinks   other scenarios can be found in Redirection 3xx chapter of HTTP 1 1 specification

User · Answer

We found it practical and useful to put the version in the URL   It makes it easy to tell what you re using at a glance   We do alias  foo to  foo  latest versions  for ease of use  shorter   cleaner URLs  etc  as the accepted answer suggests   Keeping backwards compatibility forever is often cost-prohibitive and or very difficult   We prefer to give advanced notice of deprecation  redirects like suggested here  docs  and other mechanisms

[rest] Best practices for API versioning?

Examples related to rest

Examples related to versioning