What is API Versioning?
Evolving an API without breaking existing clients: versioned paths or headers, additive changes first, removals on a schedule. Versioning is a promise that yesterday’s integration keeps working tomorrow.
Related terms
Breaking-Change Policy
Written rules for what counts as breaking, how it is announced, and how long old behavior survives. Good policy pairs deprecation windows with Sunset headers so upgrades are scheduled, never sprung.
Sunset Header
An HTTP response header announcing when an endpoint version retires, paired with migration guidance. Sunset headers turn surprise breakage into a planned upgrade with a date clients can schedule around.
OpenAPI Contract
A machine-readable spec describing every route, schema, and error so clients and tests generate from truth. BYOB treats the OpenAPI file as the API contract: code, docs, and mocks all derive from it.
REST Resource Design
Modeling an API as nouns with stable URLs — /projects/:id/messages — instead of action endpoints. Resource design makes caching, auth scoping, and client reasoning predictable across every route.
Idempotent HTTP Verbs
GET, PUT, and DELETE produce the same result when safely retried; POST does not promise that. BYOB server routes use idempotent verbs for mutations clients may repeat after network timeouts.
Retry, Backoff & Jitter
Retrying failed calls after growing delays with random spread, so a fleet does not stampede a recovering service. Exponential backoff plus jitter turns synchronized thundering herds into gentle background noise.