← API

External API Version Will Map to Different Internal API Versions

Context and Problem Statement

We have a system architecture where functionality is split amongst separate services. In some situations, a service might have its own unique version numbering scheme. In other situations, a service might be the new replacement for an existing service.

We have an external API that represents the collection of APIs that 3rd party developers can use in an official capacity.

How will we handle API versioning?

Decision Drivers

  • Consistency for external API consumers (e.g. 3rd party developers)

Decision Outcome

Chosen option: Have the External API Version Map to Different Internal API Versions.

Non-breaking changes to internal APIs can exist as part of the same external API version. Examples of non-breaking changes include:

  • Adding new APIs that did not previously exist as part of the external API.
  • Adding properties/attributes to an API endpoint that is part of the existing external API.

Mapping of internal API versions to the external API version is handled by the API Gateway.

Breaking changes to an internal API would require a new version of the external API.

Considered Options

  • Have the External API Version Map to Different Internal API Versions
  • Don’t Have an External API Version, and Expose the Underlying Internal API Versions
  • Have All Internal API Versions at the Same Version

Pros and Cons of the Options

For each of the Options, assume an example where we have these existing internal API paths:

  • Accounts - /v1/accounts, where the internal API version is at v1
  • Transactions - /v235/transactions, where the internal API version is at v235

Assume that a 3rd party developer wants to use the external API (as rendered by the API Gateway).

Have the External API Version Map to Different Internal API Versions

For this option, the external API paths might look like:

  • /api/v0/accounts

  • /api/v0/transactions

  • Good, because it allows 3rd party developers to understand where they stand with regard to API version compatibility.

  • Bad, because it incurs some additional work for the API Gateway.

Don’t Have an External API Version, and Expose the Underlying Internal API Versions

For this option, the external API paths might look like:

  • /api/v1/accounts

  • /api/v235/transactions

  • Good, because this doesn’t incur any additional work for the API Gateway.

  • Bad, because it doesn’t provide a clear picture to 3rd party developers about where they stand with regard to API version compatibility.

  • Bad, because it breaks through the abstraction of the external API and exposes underlying implementation details of our system architecture that aren’t the concern of 3rd party developers.

Have All Internal API Versions at the Same Version

For this option, the external API paths might look like:

  • /api/v0/accounts
  • /api/v0/transactions

(Note: In this example, the external paths all appear the same and the internal paths have all been forced into the same version, which could be v0, v1, or v235 depending upon the least painful internal versioning transition.)

  • Good, because it allows 3rd party developers to understand where they stand with regard to API version compatibility.
  • Good, because this doesn’t incur any additional work for the API Gateway.
  • Bad, because this imposes a versioning scheme that doesn’t match the practical reality of our software development lifecycle and how our APIs are developed.
  • Bad, because this imposes external specification details on the internal system software lifecycle.