Endpoint BayISSUE #19 of 45

versioning · /v1/ · headers · subdomains

RestaVSThe 401 Bandit

Resta saysVersioning lets an API evolve without breaking existing clients.

Once clients depend on your API, you can't change its shape freely. Version it: in the path (/v1/users — most common and visible), via a header (Accept: application/vnd.api+json;version=1), or by subdomain. Add the new version alongside the old, migrate clients, then deprecate. Path versioning is the pragmatic default.

Power-ups you unlock

/v1/ path versioning (common, visible)
Header or subdomain versioning alternatives
Run new alongside old, then deprecate
Never break existing clients silently

The 401 Bandit attacks — common mistakes

Breaking changes with no version bump
Too many live versions to maintain
No deprecation timeline communicated

Boss battleShow two ways to request v2 of a users endpoint.

Example code

<!doctype html><html><head><meta charset="utf-8"></head>
<body style="background:#06040d;color:#e6e0ff;font-family:monospace;padding:20px"><pre>path:   GET /v2/users
header: GET /users
        Accept: application/json; version=2</pre></body></html>

▶ Open the interactive comic issue

‹ Filtering · Sorting · Query Params Graphql · Query Language For Apis ›