This document aims to analyze and provide a discussion frame for multiple HTTP API versioning design approachs and strategies.

This is a work in progress

I believe that software is social by nature. Software is about building abstract things that a computer can understand. Software is also about interfaces. Interfaces are a concrete and consistent provided by software components to achieve the hability to became social, and therefore, getting the hability to interchange information with other software components.

This repository aims to collect and provide an open debate about design best practices and approachs for a consistent HTTP API versioning

Additionally, the goal is to mitigate common dilemmas about how to apply a proper HTTP versioning, and avoid unproductive and repetivie chats with your team about this kind of decissions.

The idea about creating an specific documentation for this topic was originated as result of a discusision thread at http-api-design repository.

Using Version or X-Version headers

Example:

GET /resource HTTP/1.1
Version: 1.0

• More explitict Explicit.
• HTTP is an extensible application protocol. Adding custom headers is fine.

• No fully HTTP standard focused.
• All the HTTP must have the ability to add custom headers.

Proposed mechanism from http-api-design.

Example:

GET /resource HTTP/1.1
Accept: application/json; version=1.0

Example:

GET /v1/resource HTTP/1.1

Copyright the project contributors.

Released under a Creative Commons Attribution 3.0 Unported License.