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. 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.
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.