Get full access to Hands-On Software Engineering with Golang and 60K+ other titles, with a free 10-day trial of O'Reilly.

There are also live events, courses curated by job role, and more.

Start your free trial

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 the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Don’t leave empty-handed

Get Mark Richards’s Software Architecture Patterns ebook to better understand how to design components—and how they should interact.

It’s yours, free.

Get it now

Check it out now on O’Reilly

Dive in for free with a 10-day trial of the O’Reilly learning platform—then explore all the other resources our members count on to build skills and solve problems every day.

Start your free trial Become a member now