Versionamento

Come funziona

Il percorso porta la versione maggiore, come in /v1/api/properties. Una seconda versione maggiore significherebbe una riprogettazione completa, affiancherebbe la v1 invece di sostituirla, e non è qualcosa che intendiamo fare alla leggera.

L'evoluzione quotidiana passa invece da una revisione datata. Fissala con un'intestazione e la tua integrazione mantiene il comportamento per cui è stata scritta:

Skautik-Version: 2026-08-01

Se ometti l'intestazione si applica la revisione predefinita della tua organizzazione, cioè quella in vigore quando è stata creata la tua prima chiave. Non viene spostata in avanti in silenzio, quindi un'integrazione non può rompersi perché noi abbiamo rilasciato qualcosa. Ogni risposta riporta la revisione che l'ha servita.

Cosa possiamo cambiare senza una nuova revisione

Questi cambiamenti sono additivi, e un client che segue una sola regola li tollera tutti: ignora i campi che non riconosci. Un analizzatore che rifiuta proprietà sconosciute si romperà al nostro prossimo rilascio, ed è evitabile.

• Un nuovo endpoint.
• Un nuovo parametro di richiesta facoltativo.
• Un nuovo campo in una risposta esistente.
• Un nuovo valore in un'enumerazione che ti limiti a leggere.
• Un nuovo tipo di evento webhook.
• L'allentamento di una regola di validazione che prima rifiutava qualcosa.

Cosa richiede una nuova revisione

Tutto ciò che potrebbe rompere un client corretto riceve una nuova revisione datata. La tua revisione fissata continua a comportarsi come documentato.

• Rimuovere o rinominare un endpoint, un parametro o un campo di risposta.
• Cambiare il tipo o l'unità di un campo esistente.
• Rendere obbligatorio un parametro facoltativo, o irrigidire la validazione.
• Cambiare il valore predefinito di un parametro.
• Cambiare il significato di un valore di enumerazione esistente.
• Rimuovere un tipo di evento webhook.

Dismissione

Quando qualcosa è in via di uscita continua a funzionare e comincia ad annunciarsi. Gli endpoint dismessi restituiscono:

Deprecation: true
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Link: <https://skautik.com/docs/developers/api/properties>; rel="deprecation"

• Almeno 12 mesi fra un avviso di dismissione e la rimozione, per qualsiasi cosa presente in una revisione pubblicata.
• Scriviamo al referente tecnico dell'organizzazione quando una dismissione comincia, e di nuovo all'avvicinarsi della data di spegnimento, invece di contare sul fatto che tu legga un registro delle modifiche.
• Metti un allarme sull'intestazione Deprecation nel tuo monitoraggio. È il preavviso più precoce possibile e sorvegliarlo non costa nulla.

Scrivere un client duraturo

• Fissa la revisione in modo esplicito invece di affidarti al valore predefinito del tuo account.
• Ignora campi e valori di enumerazione sconosciuti invece di fallire su di essi.
• Tratta gli identificatori come stringhe opache; non analizzare mai un prefisso in cerca di significato.
• Non dipendere dall'ordine dei campi, dall'assenza di un campo, né da un conteggio che l'API non promette.
• Ramifica sui codici di errore, non sulla prosa degli errori.