# Ripristinare una revisione della configurazione

`POST /v1/config-revisions/{revision_id}:restore` · permessi `config:write`, `config:read` e i permessi di lettura dei tipi della revisione

Crea un nuovo [piano](../config-plans/create.md) che annulla l'applicazione che ha salvato la revisione. Non cambia ancora nulla: esamina il piano, poi applicalo con [`POST /v1/config-plans/{plan_id}:apply`](../config-plans/apply.md). Il ripristino segue lo stesso percorso piano → applicazione di ogni altra modifica, quindi si applicano le stesse regole su obsolescenza, conferma delle eliminazioni, segreti e permessi.

L'obiettivo del piano è la revisione:

- Le risorse che l'applicazione ha aggiornato o eliminato riottengono la specifica che avevano prima dell'applicazione. Le risorse eliminate vengono create di nuovo.
- Le risorse che l'applicazione ha creato vengono eliminate. In questo caso il piano ha `prune: true` e copre ogni risorsa attuale dei tipi della revisione; le risorse che l'applicazione non ha toccato sono pianificate come `no_op`, quindi vengono eliminate solo quelle create. Applicarlo richiede `confirm_deletions`, come per ogni piano con eliminazioni.
- I tipi che la revisione non copre non vengono toccati.

Le revisioni non contengono valori segreti. Una connessione creata di nuovo richiede il suo client secret quando il piano viene applicato (`requires_secret`, un avviso `secret_required`). Un segreto modificato dall'applicazione originale non viene ripristinato.

## Richiesta

| Parametro | Descrizione |
|---|---|
| `revision_id` | L'id della revisione, `cfgr_…`, dall'[elenco delle revisioni](list.md). |

La richiesta non ha corpo. Sono accettati un corpo vuoto, `{}` o `null`; ogni campo viene rifiutato. Invia un header `Idempotency-Key` per rendere sicuri i tentativi ripetuti.

## Risposta

`201 Created` con `Location: /v1/config-plans/{plan_id}` e `Cache-Control: no-store`. Il corpo è un piano, nella stessa forma della [risposta alla creazione del piano](../config-plans/create.md). Il piano è valido per 1 ora e conta nel limite di frequenza e nella quota di piani dell'ambiente. La voce `config_plan.created` nel log di gestione dell'ambiente registra che il piano proviene da questa revisione.

## Errori

| HTTP | code | Quando |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | Il corpo non è vuoto, `{}` o `null`. |
| 401 | `unauthenticated` | La credenziale è mancante, non valida o revocata. |
| 403 | `insufficient_permissions` | La credenziale non ha un permesso richiesto dal piano; `required_permissions` le elenca tutte. |
| 404 | `not_found` | La revisione non esiste, appartiene a un altro ambiente o ha più di 90 giorni. |
| 413 | `config_document_too_large` | Il documento del piano supererebbe 5.000 risorse o 10 MiB. |
| 422 | `validation_failed` | La revisione non può più essere ripristinata; vedi sotto. `errors[].pointer` punta alla revisione (`/revision/<kind>/<key>/...`). |
| 429 | `rate_limited` | È stato raggiunto il limite di frequenza dei piani o la quota di piani dell'ambiente; riprova dopo il periodo indicato in `Retry-After`. |
| 503 | `service_unavailable` | La capacità di pianificazione è esaurita o una dipendenza non è temporaneamente disponibile; riprova dopo il periodo indicato in `Retry-After`. |

| `errors[].code` | Significato |
|---|---|
| `not_restorable` | `/revision_id`: la revisione copre un tipo che non esiste più. |
| `invalid` | Una specifica memorizzata non corrisponde più allo schema di configurazione attuale. |
| `unresolved_reference` | Una risorsa ripristinata fa riferimento a una `key` che non esisterà. |
| `key_in_use` | La `key` ora appartiene a un'applicazione o a un'API che la configurazione non gestisce. |
| `still_referenced` | `/revision/created`: una risorsa creata dall'applicazione è ancora referenziata da una risorsa che resta. |

## Esempio

```bash
curl -X POST "https://api.eu.keenauth.com/v1/config-revisions/cfgr_01m4qpqtywfs7930tb6kqn5rc5:restore" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

keenauth config revisions restore cfgr_01m4qpqtywfs7930tb6kqn5rc5
keenauth config apply cfgp_01m4qpqtywfs7930tb6kqn5rc5
```