# API versioning

# API versioning

The inbound sync API is versioned by URL prefix — `/api/v1/*`. The registry in `config/api.php` declares each version's lifecycle and the `api.version` middleware (alias for `App\Http\Middleware\EnforceApiVersion`) enforces it on the route group.

## Lifecycle states

| Status | Behavior |
|---|---|
| `current` | Fully supported. Responses carry `X-API-Version`. |
| `deprecated` | Still served, plus `Deprecation` (RFC 9745), `Sunset` (RFC 8594) and `Link: rel="deprecation"` headers. |
| `sunset` | Requests get `410 Gone` with an `application/problem+json` body pointing at the migration target. |

A version also auto-retires once its `sunset_at` date passes — no flag flip needed.

## Adding a version

1. Create the controllers under `App\Http\Controllers\Api\V2`.
2. Add a `Route::prefix('v2')->middleware(['api.version:v2', ...])` group in `routes/api.php`.
3. Register `'v2'` in `config/api.php` and flip `v1` to `deprecated` with `deprecated_at`/`sunset_at` dates.

## Unversioned routes — stable contract

`/api/embed/*`, `/{company}/direct-booking`, `/{eventType}/event-type-booking` and `/webhooks/*` are **not** versioned: external sites embed them and cannot migrate on our schedule. Breaking changes there need a parallel route, never an edit.


---
> Source: https://placeful-app.com/en/docs/developer/api-versioning