Learn VisualLearn API

Put the Version in the URL or a Header, and Design Changes That Need No New Version

URL versioning puts the version in the path, like /v2/orders. It is easy to see and simple to route, but every resource's URL changes whenever the version changes.

Header versioning puts the version in a request header instead, like Accept: application/vnd.api+json;version=2. Resource URLs stay the same across versions, but the version is less visible than when it sits in the URL itself.

Either way, the goal is to minimize how often a new version is needed at all. Not every change requires a new version.

When the server adds a new optional field, existing clients keep working without changes, so the change is non-breaking. Removing a field or changing its type breaks an assumption existing clients already rely on, so that change is breaking.

GOAL

Compare URL-based and header-based API versioning, and distinguish a breaking change from a non-breaking one that doesn't require a new version.

An API adds a new optional field to an existing response, which older clients simply ignore since they don't look for it. Does this require a new API version?