Stabilità e versioning 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 |
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.