API-Stabilität, Versionierung und Veraltung
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 |
Veraltungsrichtlinie
Abschnitt betitelt „Veraltungsrichtlinie“Bevor eine stabile Operation entfernt wird, wird sie mit einem Sunset-Datum als veraltet markiert. Die API-Referenz kennzeichnet die Operation als veraltet, und ihre OpenAPI-Definition enthält deprecated: true sowie das Sunset-Datum in x-sunset (YYYY-MM-DD).
- Eine veraltete stabile Operation funktioniert bis zu ihrem Sunset-Datum weiter und kann ab diesem Datum entfernt werden.
- Es gibt keine feste Mindestfrist: Das Sunset-Datum jeder Veraltung ist ihre Ankündigung.
- Ein veralteter Anfrageparameter mit Sunset-Datum folgt derselben Regel.
- Einige Abfrageparameter werden mit einem abwärtskompatiblen Alias umbenannt: Der alte Name funktioniert weiterhin neben dem neuen.
- Experimentelle Operationen sind ausgenommen: Sie können ohne Sunset-Datum als veraltet markiert und ohne Vorankündigung geändert oder entfernt werden, siehe Experimentelle Operationen.
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.