API-stabiliteit en versiebeheer
Voordat u langdurig bouwt op de RealityConnect API, moet u weten welke delen van het oppervlak stabiel zijn, hoe experimentele operaties worden gemarkeerd, en wat u kunt verwachten tussen updates.
Experimentele operaties
Section titled “Experimentele operaties”Sommige operaties in de API-referentie dragen een experimentele stabiliteitsmarkering. Zoek naar x-scalar-stability: experimental op een operatie in het OpenAPI-document (zichtbaar als stabiliteitsbadge in de gerenderde API-referentie) om ze te herkennen. Dit wordt automatisch synchroon gehouden met de API, controleer dat dus liever dan te vertrouwen op een vaste lijst hier.
Experimentele operaties zijn echt en aanroepbaar (niet uitgeschakeld of alleen een preview), maar hun paden, parameters, payloads, responses of beschikbaarheid kunnen veranderen zonder dezelfde stabiliteitsgaranties als de rest van de API. Zie Aan de slag: Experimentele endpoints voor hoe u ermee werkt.
Wanneer een experimentele operatie stabiel wordt, wordt dat aangekondigd in de release notes.
Breaking versus non-breaking wijzigingen
Section titled “Breaking versus non-breaking wijzigingen”| Wijziging | Breaking? | Waarom |
|---|---|---|
| Nieuwe optionele requestparameter | Nee | Bestaande requests blijven ongewijzigd werken |
| Nieuw responseveld | Nee | Bestaande clients die bekende velden lezen worden niet beïnvloed; parse responses tolerant en negeer onbekende velden |
| Nieuwe enum-waarde toegevoegd aan een bestaand veld | Nee | Behandel enum-velden als open verzamelingen en handel onbekende waarden soepel af, in plaats van elke bekende waarde uitputtend te matchen |
| Bestaand veld verwijderd of hernoemd | Ja | Breekt elke client die dat veld leest |
| Type of betekenis van een bestaand veld gewijzigd | Ja | Breekt elke client die op de vorige vorm vertrouwt |
| Verplichte parameter toegevoegd aan bestaande operatie | Ja | Breekt bestaande requests die deze niet meesturen |
| Endpointpad of HTTP-methode gewijzigd | Ja | Breekt bestaande requests volledig |
| Contract van een experimentele operatie verandert | Nee (bedoeld) | Experimentele operaties zijn expliciet uitgezonderd van het stabiliteitscontract; zie hierboven |
Wat is de volgende stap?
Section titled “Wat is de volgende stap?”- Zie de API-referentie voor de huidige stabiliteitsmarkering en het request- en responseschema per operatie.
- Zie Aan de slag voor het beveiligingsmodel en het kiezen van een OAuth-flow.