# Versionamento API

# Versionamento API

L'API di sincronizzazione in ingresso è versionata tramite prefisso URL — `/api/v1/*`. Il registro in `config/api.php` dichiara il ciclo di vita di ogni versione e il middleware `api.version` (alias di `App\Http\Middleware\EnforceApiVersion`) lo applica al gruppo di rotte.

## Stati del ciclo di vita

| Stato | Comportamento |
|---|---|
| `current` | Pienamente supportata. Le risposte portano `X-API-Version`. |
| `deprecated` | Ancora servita, con header `Deprecation` (RFC 9745), `Sunset` (RFC 8594) e `Link: rel="deprecation"`. |
| `sunset` | Le richieste ricevono `410 Gone` con corpo `application/problem+json` che indica la versione di destinazione. |

Una versione si ritira automaticamente al superamento di `sunset_at` — nessun intervento manuale.

## Aggiungere una versione

1. Crea i controller in `App\Http\Controllers\Api\V2`.
2. Aggiungi un gruppo `Route::prefix('v2')->middleware(['api.version:v2', ...])` in `routes/api.php`.
3. Registra `'v2'` in `config/api.php` e imposta `v1` su `deprecated` con le date `deprecated_at`/`sunset_at`.

## Rotte non versionate — contratto stabile

`/api/embed/*`, `/{company}/direct-booking`, `/{eventType}/event-type-booking` e `/webhooks/*` **non** sono versionate: i siti esterni le incorporano e non possono migrare secondo i nostri tempi. Le modifiche non retrocompatibili richiedono una rotta parallela, mai una modifica.


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