API-Stabilität und Versionierung
Bevor Sie langfristig auf der RealityConnect API aufbauen, sollten Sie wissen, welche Teile der Oberfläche stabil sind, wie experimentelle Operationen markiert werden und was Sie über Upgrades hinweg erwarten können.
Experimentelle Operationen
Abschnitt betitelt „Experimentelle Operationen“Einige Operationen in der API-Referenz tragen eine experimentelle Stabilitätsmarkierung. Suchen Sie im OpenAPI-Dokument nach x-scalar-stability: experimental an einer Operation (sichtbar als Stabilitäts-Badge in der gerenderten API-Referenz), um sie zu identifizieren. Dies wird automatisch mit der API synchron gehalten, prüfen Sie also dort und verlassen Sie sich nicht auf eine feste Liste hier.
Experimentelle Operationen sind real und aufrufbar (nicht deaktiviert oder nur eine Vorschau), aber ihre Pfade, Parameter, Payloads, Antworten oder Verfügbarkeit können sich ändern, ohne dieselben Stabilitätsgarantien wie der Rest der API zu bieten. Siehe Erste Schritte: Experimentelle Endpunkte für den Umgang damit.
Wenn eine experimentelle Operation stabil wird, wird dies in den Release Notes angekündigt.
Breaking Changes vs. nicht-breaking Changes
Abschnitt betitelt „Breaking Changes vs. nicht-breaking Changes“| Änderung | Breaking? | Warum |
|---|---|---|
| Neuer optionaler Anfrageparameter | Nein | Bestehende Anfragen funktionieren unverändert weiter |
| Neues Antwortfeld | Nein | Bestehende Clients, die bekannte Felder lesen, sind nicht betroffen; Antworten tolerant parsen und unbekannte Felder ignorieren |
| Neuer Enum-Wert für ein bestehendes Feld | Nein | Enum-Felder als offene Mengen behandeln und unbekannte Werte tolerieren, statt jeden bekannten Wert erschöpfend abzugleichen |
| Bestehendes Feld entfernt oder umbenannt | Ja | Bricht jeden Client, der dieses Feld liest |
| Typ oder Bedeutung eines bestehenden Felds geändert | Ja | Bricht jeden Client, der sich auf die vorherige Form verlässt |
| Erforderlicher Parameter zu bestehender Operation hinzugefügt | Ja | Bricht bestehende Anfragen, die ihn nicht senden |
| Endpunktpfad oder HTTP-Methode geändert | Ja | Bricht bestehende Anfragen vollständig |
| Vertrag einer experimentellen Operation ändert sich | Nein (beabsichtigt) | Experimentelle Operationen sind ausdrücklich vom Stabilitätsvertrag ausgenommen; siehe oben |
Wie geht es weiter?
Abschnitt betitelt „Wie geht es weiter?“- Siehe die API-Referenz für die aktuelle Stabilitätsmarkierung sowie Anfrage- und Antwortschema pro Operation.
- Siehe Erste Schritte für das Sicherheitsmodell und die Wahl eines OAuth-Flows.