# Versionamento e stabilità

Come viene versionata l’API, quali modifiche possono arrivare senza una nuova versione maggiore e come fissarsi alla v1.

PDF Blocks versiona l’API in modo che si possano adottare i miglioramenti senza
temere rotture a sorpresa. Le regole qui sotto dicono esattamente quali modifiche
si possono ricevere automaticamente senza rischi e come arriverebbe una modifica
incompatibile.

## Versionamento semantico

L’API segue il [versionamento semantico 2.0.0](https://semver.org). Dato un
numero di versione `X.Y.Z`:

| Parte | Nome     | Significato                                     |
| ----- | -------- | ----------------------------------------------- |
| `X`   | Maggiore | Modifiche non retrocompatibili.                 |
| `Y`   | Minore   | Aggiunte di funzionalità retrocompatibili.      |
| `Z`   | Patch    | Correzioni di bug retrocompatibili.             |

La versione attuale della specifica è `1.18.0`. La versione in vigore si può
sempre leggere nel campo `info.version` della [specifica
OpenAPI](/docs/api/openapi-specification).

## La versione maggiore `v1` nel percorso

La versione **maggiore** è fissata nel percorso dell’URL: ogni azione vive sotto
`/v1/`, come in `https://api.pdfblocks.com/v1/add_text_watermark`. Le versioni
minori e le patch vengono rilasciate sul posto, sotto `/v1/`. Si ricevono
automaticamente e non serve mai cambiare i propri URL per ottenerle. Poiché le
modifiche incompatibili vengono rilasciate solo sotto una nuova versione maggiore
(un nuovo segmento di percorso), restare su `/v1/` significa restare su un
contratto stabile.

## Che cosa conta come retrocompatibile

All’interno della `v1` facciamo modifiche additive senza una nuova versione
maggiore. Considerare tutto quanto segue come qualcosa che può comparire in
qualsiasi momento, e scrivere client che lo tollerino:

- **Nuovi parametri facoltativi** su un’azione esistente.
- **Nuovi valori accettati** per un parametro esistente: un’enumerazione
  allargata o ampliata.
- **Alias di parametri**: un nuovo nome per un campo esistente, con il vecchio
  nome ancora accettato.
- **Risposte più ricche**: nuovi campi nel corpo di una risposta o nuove
  intestazioni di risposta.
- **Nuove azioni e nuovi endpoint.**

Nessuna di queste modifiche obbliga a fissare una versione minore o a cambiare il
proprio codice. Per restare compatibili, ignorare i campi della risposta che non
si riconoscono invece di considerarli un errore, e non dare per scontato che
un’enumerazione sia un insieme fisso ed esaustivo.

## Come vengono rilasciate le modifiche incompatibili

Una modifica incompatibile (la rimozione o la ridenominazione di un parametro
obbligatorio, la modifica di una risposta in modo incompatibile o l’alterazione
di un comportamento consolidato) verrebbe rilasciata solo come **nuova versione
maggiore su un nuovo percorso**, per esempio `/v2/`. Le chiamate `/v1/` esistenti
continuano a funzionare invariate e la migrazione avviene secondo i propri tempi.
Non facciamo modifiche incompatibili sul posto sotto `/v1/`.

## Fissare una versione maggiore

Fissare la propria integrazione alla versione maggiore `v1` mantenendo `/v1/`
negli URL delle richieste. È tutto quello che serve: si ricevono automaticamente
i miglioramenti retrocompatibili delle versioni minori e delle patch, mentre le
modifiche incompatibili restano fuori dal proprio percorso finché non si sceglie
di adottare una futura versione maggiore.

Per seguire che cosa è cambiato in ogni rilascio, vedere il [Registro delle
modifiche](/docs/api/changelog).