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?

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.