5

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?

jakejgordon
  • 3,778
  • 6
  • 31
  • 43
  • Also for what it is worth Check mnot's article on versioning https://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown – Zdenek Feb 25 '16 at 14:08

1 Answers1

6

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.

Almad
  • 5,357
  • 6
  • 28
  • 46
  • 1
    Ok, so there isn't really any special support for URL versioning in Apiary at this time. Fair enough. – jakejgordon Oct 22 '15 at 17:23
  • @jakejgordon How would "special support" look like? – Almad Oct 22 '15 at 17:25
  • 2
    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. – jakejgordon Oct 23 '15 at 00:55