Skip to content
releo

API glossary

What is API versioning?

API versioning is the practice of exposing multiple versions of an API at once so providers can ship breaking changes while existing clients keep using the version they were built for.

API versioning, explained

Common strategies put the version in the URL path (/v2/), in a header or media type, in a query parameter, or use dated versions such as 2024-06-01. Each trades visibility, granularity and operating cost differently.

Versioning defers migrations; it does not perform them. Every consumer still has to move eventually, and the provider pays to run old versions until they do.

  • Semantic versioning (SemVer): Semantic versioning is a MAJOR.MINOR.PATCH numbering scheme where a major bump signals a breaking change, a minor bump adds backward-compatible features, and a patch fixes bugs.
  • API deprecation: API deprecation is the formal announcement that an endpoint, field or version is going away, with a timeline for clients to migrate before it is removed.
  • Breaking change: A breaking change is a change to an API that causes a correctly written client, which worked before, to fail or behave differently without modifying its code.

Coming soon

Ship API changes without breaking your customers.

Releo is in private beta. Join the waitlist for early access.