# API versioning strategy

**URL:** <https://www.ruby-forum.com/t/api-versioning-strategy/155690>\
**Category:** Rails\
**Created:** [December 15, 2008, 4:48pm UTC](https://www.ruby-forum.com/t/api-versioning-strategy/155690 "2008-12-15T16:48:53Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![zaczheng](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/z/edb3f5/32.png) [@zaczheng](https://www.ruby-forum.com/u/zaczheng)\
**Post date:** [December 15, 2008, 4:48pm UTC](https://www.ruby-forum.com/t/api-versioning-strategy/155690/1 "2008-12-15T16:48:53Z")

</div>

I am developing a service to be accessed within a browser and via API. I  
am not sure what the best practise for API versioning is.

AdWords API split into major version by URI mutilation: /v1, /v2 etc.

My current thoughts are:

Website accessible from [www.myservice.com](http://www.myservice.com)  
API accessible from [v1.myserviceapi.com](http://v1.myserviceapi.com) This will be a separate instance  
with its own mongrels/mod\_rails.

Major updates will go under a incremented subdomain,  
[v2.myserviceapi.com](http://v2.myserviceapi.com). This will happen infrequently. Perhaps once a year.

Minor updates will be a normal capistrano deploy.

Can anyone please comment on the above? It’s much appreciated.

Zac

---

<div class="post-metadata">

**Author:** ![zaczheng](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/z/edb3f5/32.png) [@zaczheng](https://www.ruby-forum.com/u/zaczheng)\
**Post date:** [December 20, 2008, 12:52pm UTC](https://www.ruby-forum.com/t/api-versioning-strategy/155690/2 "2008-12-20T12:52:55Z")

</div>

From what I can tell, your strategy of [v1.example.com](http://v1.example.com) and  
[v2.example.com](http://v2.example.com) work well. Another strategy is [api.example.com/v1/](http://api.example.com/v1/)…  
and [api.example.com/v2/](http://api.example.com/v2/)…

I personally prefer the latter, but it means everything listening on  
[api.example.com](http://api.example.com) must speak both protocols, or you have to have a fancy  
redirector that inspects packets.

–Michael

On Mon, Dec 15, 2008 at 3:48 PM, Zac Z.

---

<div class="post-metadata">

**Author:** ![zaczheng](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/z/edb3f5/32.png) [@zaczheng](https://www.ruby-forum.com/u/zaczheng)\
**Post date:** [December 20, 2008, 7:43pm UTC](https://www.ruby-forum.com/t/api-versioning-strategy/155690/3 "2008-12-20T19:43:49Z")

</div>

For service apis with end point on the network, it’s usually preferred  
to keep the end point stable as you don’t want to your client apps to  
change often when you start versioning. If your new version breaks  
compatibility significantly, then it’s ok to have a new end point but  
otherwise the versioning might be better handled at the message level.  
ie, your message may have a header with v=v1, etc.

Regards,

# rp8

> **[Competo Solutions, Inc.](https://competo.com/)**
>
> Sharing our experience in ever changing tech landscapes

Zac Z. wrote:

> I am developing a service to be accessed within a browser and via API. I  
> am not sure what the best practise for API versioning is.
> 
> AdWords API split into major version by URI mutilation: /v1, /v2 etc.
> 
> My current thoughts are:
> 
> Website accessible from [www.myservice.com](http://www.myservice.com)  
> API accessible from [v1.myserviceapi.com](http://v1.myserviceapi.com) This will be a separate instance  
> with its own mongrels/mod\_rails.
> 
> Major updates will go under a incremented subdomain,  
> [v2.myserviceapi.com](http://v2.myserviceapi.com). This will happen infrequently. Perhaps once a year.
> 
> Minor updates will be a normal capistrano deploy.
> 
> Can anyone please comment on the above? It’s much appreciated.
> 
> Zac