Skip to main content

Versioning a JSON API without painting yourself into a corner

  • Laravel
  • PHP
  • APIs
  • Architecture

URL prefixes, headers, and sunset policies—pick one story and stick to it.

Clients outlive deploys. Explicit versioning—often via URL prefix like /api/v1—makes caches and documentation easier than opaque header negotiation.

When you must break a field shape, ship a new minor or major version and document a sunset date. Deprecations belong in changelogs and, when possible, in response metadata.

Resources and transformers help keep multiple versions readable in one codebase without duplicating every controller.