Stabilità, versioning e deprecazione dell'API
Prima di costruire a lungo termine sulla RealityConnect API, capisci quali parti della superficie sono stabili, come vengono contrassegnate le operazioni sperimentali e cosa aspettarti tra un aggiornamento e l’altro.
Operazioni sperimentali
Sezione intitolata “Operazioni sperimentali”Alcune operazioni nella documentazione di riferimento API portano un marcatore di stabilità sperimentale. Cerca x-scalar-stability: experimental su un’operazione nel documento OpenAPI (visibile come badge di stabilità nella documentazione di riferimento API renderizzata) per identificarle. Questo viene mantenuto automaticamente sincronizzato con l’API, quindi verifica lì piuttosto che affidarti a un elenco fisso qui.
Le operazioni sperimentali sono reali e invocabili (non disabilitate né solo in anteprima), ma i loro percorsi, parametri, payload, risposte o disponibilità possono cambiare senza le stesse garanzie di stabilità del resto dell’API. Vedi Per iniziare: Endpoint sperimentali per come lavorarci.
Quando un’operazione sperimentale si stabilizza, questo viene annunciato nelle note di rilascio.
Modifiche breaking e non breaking
Sezione intitolata “Modifiche breaking e non breaking”| Modifica | Breaking? | Perché |
|---|---|---|
| Nuovo parametro di richiesta opzionale | No | Le richieste esistenti continuano a funzionare senza modifiche |
| Nuovo campo di risposta | No | I client esistenti che leggono campi noti non sono interessati; effettua il parsing delle risposte in modo tollerante e ignora i campi non riconosciuti |
| Nuovo valore enum aggiunto a un campo esistente | No | Tratta i campi enum come insiemi aperti e gestisci con flessibilità i valori non riconosciuti, invece di confrontare in modo esaustivo ogni valore noto |
| Campo esistente rimosso o rinominato | Sì | Rompe qualsiasi client che legge quel campo |
| Tipo o significato di un campo esistente modificato | Sì | Rompe qualsiasi client che si basa sulla forma precedente |
| Parametro obbligatorio aggiunto a un’operazione esistente | Sì | Rompe le richieste esistenti che non lo inviano |
| Percorso dell’endpoint o metodo HTTP modificato | Sì | Rompe del tutto le richieste esistenti |
| Il contratto di un’operazione sperimentale cambia | No (voluto) | Le operazioni sperimentali sono esplicitamente esentate dal contratto di stabilità; vedi sopra |
Politica di deprecazione
Sezione intitolata “Politica di deprecazione”Prima di essere rimossa, un’operazione stabile viene deprecata con una data di dismissione (sunset). Il riferimento API contrassegna l’operazione come deprecata, e la sua definizione OpenAPI riporta deprecated: true e la data di dismissione in x-sunset (YYYY-MM-DD).
- Un’operazione stabile deprecata continua a funzionare fino alla data di dismissione, e può essere rimossa a partire da quella data.
- Non esiste un periodo minimo di preavviso fisso: la data di dismissione di ogni deprecazione costituisce il preavviso.
- Un parametro di richiesta deprecato con data di dismissione segue la stessa regola.
- Alcuni parametri di query vengono rinominati con un alias retrocompatibile: il vecchio nome continua a funzionare insieme al nuovo.
- Le operazioni sperimentali sono escluse: possono essere deprecate senza data di dismissione, e modificate o rimosse senza preavviso, come indicato in Operazioni sperimentali.
Cosa c’è dopo?
Sezione intitolata “Cosa c’è dopo?”- Vedi la documentazione di riferimento API per il marcatore di stabilità attuale e lo schema di richiesta e risposta di ogni operazione.
- Vedi Per iniziare per il modello di sicurezza e come scegliere un flusso OAuth.