Including the API version as a route prefix

The most popular approach for implementing API versioning is for clients to include the requested API version as part of the requested API endpoint paths. For instance, /v1/account and /v2/account are versioned endpoints for retrieving the user's account details. However, the /account endpoint, when mounted under the v2 prefix, might return a completely different payload than the one mounted under the v1 prefix.

The choice of the version naming scheme is totally arbitrary and is up to the API designer to decide on. Common versioning schemes include the following:

  • Numeric values; for example, v4
  • API release dates; for example, 20200101
  • Season names that coincide with new API releases; for example,  ...

Get Hands-On Software Engineering with Golang now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.