CleanedWeb

Glossary

API versioning

API versioning is how a provider labels changes to an API so that existing callers keep working while it evolves. A version tells you which contract, meaning which fields, types and inputs, a response follows.

Common approaches

Providers put the version in the URL (/v2/items), in a header or query parameter, or use dates. Most separate two kinds of change. A breaking change is one an old caller cannot survive, such as a removed or retyped field or a new required input. A compatible change, such as a new optional field, is safe to ship inside the same version. The first kind earns a new major version.

As a caller, pin the version you tested, ignore fields you do not know, watch for deprecation notices such as the Deprecation and Sunset HTTP headers, and store the version with the data you collect so a later change is easy to explain.

In CleanedWeb

A published catalog API has majors (1, 2, 3). You pin a major by sending version as an integer in the run body. Inside a major every change is a minor: repairs when the source changes its markup, added fields and added optional inputs. Minors are internal, and every call on a major runs its newest minor. A call without version runs the latest major, so pin one in production.

A new major is a change the old contract cannot answer truthfully, for example a removed or retyped field or a removed input. When one goes live, the previous major is deprecated, keeps answering for 60 days, and is then sunset. Deprecated calls carry Deprecation, Sunset and Link headers. A call pinned to a sunset major is not refused: it runs on the latest major and the response says "rerouted": "sunset", so check that field. A major that never existed answers 404 (catalog_version_not_found), and an invalid value answers 422.

For an API you built yourself, the version is a definition version, a full 64-character hash you send as expected_version. If the active definition differs, the run answers 409 with builder_definition_version_conflict. Pinning guards the contract; it does not freeze the website.

Tools and docs

Related terms

All glossary entries

Build an API from a website

CleanedWeb turns a website into a maintained REST API that returns structured records, with a versioned schema and repairs when the site changes.