Does Apiary.io and/or API Blueprint support api versioning?

Question

Does api blueprint or Apiary.io support the notion of versioning your API? In particular, I'm versioning my API via the URI like this:

GET /api/v2/SomeResource/

In the example above, this means I'm calling version 2 ("v2") of the API. Does api blueprint support this? How can I document multiple versions of a given action or the entire API?

Pixilated

Also for what it is worth Check mnot's article on versioning mnot.net/blog/2011/10/25/web_api_versioning_smackdown – Oneway

Answer 1

You can use HOST header to signify that:

HOST: http://example.com/api/v2 is going to prefix all resources with /api/v2.

In the API Blueprint, if you use URL prefixing, the APIs are considered different and therefore you should use different blueprints for them.

If you use media types with version suffix to do that, you can just specify proper Content-Type in headers, and they'll be used properly for content negotiation in mock server.

Icily

Ok, so there isn't really any special support for URL versioning in Apiary at this time. Fair enough. – Pixilated

@Pixilated How would "special support" look like? – Icily

Not sure -- maybe the ability to initiate a new version of the API through the UI, pick a new version number, and then only add add new/changed actions to the newer blueprint. Doubt this could be driven only by the API blueprint file -- would probably need extra metadata in Apiary. – Pixilated