Versioning APIs

API versioning is something you should think about from the very beginning and avoid as long as you can. In general, you will need to make changes to your API, however, having to maintain n different versions can be a royal pain in the backside, so doing the upfront design thinking at the beginning can save you a whole load of trouble.

Before we look at how you can version your API, which is quite straightforward let's look at when you should version.

You would increment your API version number when you introduce a breaking change.

Breaking changes include:

• Removing or renaming APIs or API parameters
• Changing the type of an API parameter, for example, from integer to string
• Changes to response codes, error codes, or fault contracts
• Changes to the behavior of an existing API

Things that do not involve a breaking change include:

• Adding parameters to a returned entity
• Adding additional endpoints or functionality
• Bug fixes or other maintenance that does not include items in the breaking changes list