Aan de slag
Voordat u de RealityConnect API aanroept, bevestigt u dat uw netwerk deze kan bereiken, begrijpt u hoe toegang wordt afgedwongen en kiest u de OAuth-flow die bij uw integratie past. Elke flow heeft zijn eigen stapsgewijze gids.
Vereisten
Section titled “Vereisten”U hebt beheerderstoegang tot de organisatie nodig om uw eerste OAuth-applicatie te maken. Als u die nog niet hebt, kan uw organisatiebeheerder u toegang verlenen of de applicatie voor u maken.
API-URL’s en netwerktoegang
Section titled “API-URL’s en netwerktoegang”Voordat u OAuth-inloggegevens maakt, bevestigt u dat de machine of server die uw integratie uitvoert de Prevu3D API via HTTPS kan bereiken. Bedrijfsfirewalls, proxy’s en allowlists blokkeren vaak uitgaand verkeer en veroorzaken verbindingstime-outs of DNS-fouten.
Uw integratie moet het volgende kunnen bereiken:
- OAuth- en API-discovery: https://cloud-api.prevu3d.com
- Regionale RealityConnect API (uw organisatie gebruikt één regio; uw flowgids legt uit hoe u de exacte URL vindt):
Vraag uw IT-team om uitgaande HTTPS-toegang tot deze hosts toe te staan als u geen verbinding kunt maken.
Beveiligingsmodel
Section titled “Beveiligingsmodel”API-toegang wordt afgedwongen via drie lagen. Een verzoek moet alle slagen om te lukken; als een laag toegang weigert, mislukt het verzoek.
Laag 1 — OAuth-scopes. Geconfigureerd op de OAuth-applicatie. Scopes bepalen welke families van bewerkingen de applicatie mag uitvoeren (bijv. read:basic, read:hierarchy).
Laag 2 — Inhoudstoegang. Geconfigureerd op het account dat de API aanroept. Voor Client Credentials is dat de servicegebruiker die met uw OAuth-applicatie is gemaakt. Voor de Native app-flow is het de ingelogde gebruiker. Deze laag bepaalt welke nodes (organisaties, divisies, sites, enz.) de aanroeper kan zien en waarop deze actie kan ondernemen.
Laag 3 — Rol-/rechtentoegang. Geconfigureerd op datzelfde account, per node. Bepaalt wat de aanroeper met die inhoud kan doen (lezen, bewerken, beheren, enz.).
Elke flowgids doorloopt waar en hoe u deze lagen voor uw gebruiksscenario configureert.
Kies een OAuth-flow
Section titled “Kies een OAuth-flow”Kies de OAuth-flow die past bij hoe uw integratie draait en volg vervolgens de bijbehorende gids:
| Flow | Beste voor | Gids |
|---|---|---|
| Client Credentials | Server-naar-server-integraties, scripts en back-endservices die namens uw organisatie handelen | Client Credentials-flow |
| Native app | Integraties waarbij een gebruiker via een browser inlogt (desktopapps, CLI-tools, plug-ins). Gebruikt Authorization Code + Native Application met PKCE, een localhost-omleiding en geen client secret. | Native Application-flow |
| Authorization Code + aangepaste HTTPS-omleiding | Webapplicaties met een callback-URL op uw eigen domein | Authorization Code + aangepaste-omleiding-flow |
Weet u niet waar u moet beginnen? Client Credentials is het eenvoudigste pad om de API te testen of server-side-automatisering te bouwen. Gebruik de Native app-flow wanneer API-aanroepen als een specifieke ingelogde gebruiker moeten worden uitgevoerd.
Experimentele endpoints
Section titled “Experimentele endpoints”Sommige bewerkingen in de API-referentie zijn gemarkeerd als experimenteel.
Behandel experimentele endpoints anders dan stabiele:
- Verwacht verandering. Paden, parameters, payloads, responses, fouten of beschikbaarheid kunnen veranderen zonder dezelfde stabiliteitsgaranties als de rest van de API.
- Isoleer het gebruik. Geef in uw integratie de voorkeur aan stabiele bewerkingen. Als u afhankelijk bent van iets experimenteels, houd het dan achter een kleine adapter zodat u zich snel kunt aanpassen wanneer het contract evolueert.
- Blijf up-to-date. Volg de release notes en bekijk de API-referentie opnieuw na upgrades, zodat u niet wordt verrast door gedragswijzigingen.
Wat is de volgende stap?
Section titled “Wat is de volgende stap?”Kies een flow uit de volgende opties en volg de gids van begin tot eind.
Verken de API-referentie om alle beschikbare bewerkingen te zien.