API Architecture - Versioning Best Practices


Rule of Thumb for API Versioning 👍

Tip #1 - Keep a Detailed & Up-to-date API Spec

  • Contract — An API Spec is the contractual agreement between the API software engineers and the API consumers (or applications). It should list details of all the features in the API that are made available to the application.
  • Operations — The specific operation(s) that the API supports, also called methods and functions.
  • Requests — The specific request(s) that the API supports, and applications make the to API.
  • Responses — The specific response(s) that the API supports, and applications expect to receive from the API.

Tip #2 - Devise a Versioning Strategy

  1. Preserve the existing functionality(s) of existing applications
  2. Provide additional functionality(s) via new versions of the API

How to handle the versioning

Postel’s Law

  • Change responses (payloads) conservatively
  • Accept requests from applications/consumers liberally
  • Create new API versions due to any of the following changes:
    - Major changes
    - Minor changes
    - Patch updates

Surprises are not Good! In the API world at least…

  • Consumers are dependent on the calls/methods the changes involve
  • The design should reflect the following consumer attributes:
    - Schemas
    - Mental models
    - Expectations
  • Have the API match the existing expectations of the consumers
  • Build and implement the new features to behave according to existing mental models that consumers and end users have created

Tip #3 - Try to use Semantic Versioning

Patch updates

Minor changes

Major changes

Versioning effects

Leveraging Semantic Versioning

  1. Identify our APIs with the following pattern for the versioning: Major.Minor.Patch
  2. Release your API Specs initially with the first version being 1.0.0
  3. Number the versions created before the initial release as: 0.x.x
    - Quick note: The 0 indicates that the API was still in development mode.
  4. Number the minor and patch versions in sequential order from 0 .
  5. Restart the numbering for minor and patch versions at 0 when the next higher version change happens.
  6. Include the major version number in the path when creating your API.
  1. Domain
  2. Sub-domain
  3. Version
  4. Resource (coffeeshop)
  • Semantic versioning will restrict the API software engineer’s abilities to make updates and changes to the API Spec and existing APIs.
  • Minor and Patch versions SHOULD NOT introduce breaking changes.

Versioning your URIs

  • Indicate the version(s) consistently.
  • Keep different resources separate.
  • Create a new API call each time the software engineer would like to supply a newer version of the API Spec.
  • Preserve the functionality(s) of applications using the previous API.
  • Software engineers can preserve existing APIs.
  • Engineers can create new API endpoints to support the new API Specs.
  • Applications that have not fully switched over to the updated URI are unimpacted by the version change.
  • Existing consumer applications can continue to function business as usual.

Tip #5 - Handling and Onboarding Breaking Changes

Examples of Breaking Changes

  • Paths
    - Changing the basePath to any of the existing API methods
    - Changing the name of an existing resource, or collection
  • Requests
    - Adding or removing required parameters in the HTTP Headers (i.e. URL Parameters, or Request Body)
    - Adding or removing a required response header, or property from a response body
    - Adding or removing HTTP Status Codes.
  • Methods
    - Changing the behavior of the API.
    - Changing the fault tolerance/error handling behavior of the API.
"latte": {
"flavor": "Pumpkin Swirl",
"size": "Large",
"holiday": "Halloween"
"latte": {
"flavor": "Pumpkin Swirl",
"size": "Large"
  • flavor
  • syrup
  • An existing consumer application may still be using the older format of the payload
  • Engineers have not configured the existing application to consume the payload in the new format
"latte": {
"flavor": "Pumpkin",
"syrup": "Swirl",
"size": "Large",
"holiday": "Halloween"

Tip #6 - Handling and Onboarding Non-Breaking Changes

  • Incrementing the minor version by one
  • Setting the patch version back to zero

Patch changes

Routing changes

Tip #7 - Gracefully Sunset and Deprecate legacy API versions

  1. Make an announcement to inform all API users that they must move to the new version of the API. This notice should include any sunset period and when you plan to deprecate the service. Keep an up-to-date list of contacts of your API consumers.
  2. Sunset the API with a warning that defines the sunset period (ex: 1 month, x number of weeks, etc.).
  3. Deprecate the API when users have discontinued usage of the former versions.

Want to learn more about API Architecture? 📝

APIs & Technical Architecture Best Practices

5 stories



Multi-disciplinary Technical Lead specialized in building products users love. Today, I manage & secure big data in the cloud. All views shared are my own.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Abdul Wahab

Multi-disciplinary Technical Lead specialized in building products users love. Today, I manage & secure big data in the cloud. All views shared are my own.