I find it odd that on the one hand, this site is about following standards and best practices, but at the same time violates some other fundamental web standards.<p>For instance, instead of using a well-established example domain name like <i>example.com</i> [1], they misuse the existing domain <i>yourdomain.com</i> which currently belongs to Neon Network LLC.<p>[1] see RFC 2606, <a href="http://tools.ietf.org/html/rfc2606" rel="nofollow">http://tools.ietf.org/html/rfc2606</a>
A true REST purist would say that you shouldn't put versioning in the URL. Use different Content-Types for different versions of the API, and use Accept headers to indicate the version the client is using.
The one thing I would tell people implementing an HTTP API; create a non-trivial sample application using the API.<p>The benefits of this are many:<p>1) You will create a client library for your API in at least one language. You can release this along with the API which will make it easier for people to adopt the API. It will also serve as an example of best practices for interfacing with your API for other client library authors.<p>2) You will be forced to really think about what representations people using the API will want to consume. Too many people expose an API that is just a wrapper around their data models. Your data models are rarely structured in an appropriate way: i.e. a blog_post might have a user_id, but most API users would appreciate being passed some form of a user representation there, rather than make another API call.<p>3) The application serves as an end-to-end test of your API (though obviously isn't sufficient in terms of testing)
Agree completely with Adamj here - put versioning in the headers. And to be honest, the advice here implies you can as a newbie product manager design a rest api without a hardcore (presumably experienced) rest developer - and throw it over the wall to the developers (who will thank you). I cannot ever imagine that working.<p>Some recent posts on why no-one gets rest (to be looked up) are much more useful, but even so I have not yet found a good guide to rest style - even the oreilly book was disappointing.
Your reasoning for having the api at a subdomain applies for versioning is well. Imagine v1 of the api is written quickly in PHP. As the needs of the company change, you may need to iterate on the api and build v2 with Java. Managing versions by api.example.com/v1 and api.example.com/v2 would be difficult. Here are two suggestions: v1.api.example.com or v1api.example.com.
Why not put the version in the domain name? v1.api.example.com looks legit, and also <i>implies</i> that the api versions are indeed handled by different subsystems.
Not sure why would you recommend SSL from day one. If the API needs to entertain high throughput and low response time, adding SSL means adding overhead.
I don't know if there is a better way to do this, but when creating our own API we also added a $_GET['_method'] variable with 'GET|POST|PUT|DELETE' values. This was basically to override the HTTP request method. This gave us a lot of convenience calling the Rest API from flex/flash which does not support PUT/DELETE request types yet.