Menu
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?
362
APIs only need to be up-versioned when a breaking change is made. Breaking changes include: a change in the format of the response data for one or more calls. a change in the request or response type (i.e. changing an integer to a float)
API versioning is the practice of transparently managing changes to your API. Managing an API boils down to defining and evolving data contracts and dealing with breaking changes. The most effective way to evolve your API without breaking changes is to follow effective API change management principles.
An apiary (also known as a bee yard) is a location where beehives of honey bees are kept. Apiaries come in many sizes and can be rural or urban depending on the honey production operation. Furthermore, an apiary may refer to a hobbyist's hives or those used for commercial or educational usage.
API Blueprint is a high-level language for describing web APIs. The syntax is a combination of Markdown syntax and Markdown Syntax for Object Notation (MSON), and the files are saved with a . apib extension.
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.
81
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
