Wat contextId accepteert

contextId is een verplichte padparameter op elke /v1/twin/{contextId}/...- en /v1/reality-plan/{contextId}/...-route. Hij is polymorf: meerdere verschillende id-types worden erdoor opgelost, wat verklaart waarom een correct gevormde UUID toch 404 kan opleveren. Deze pagina beschrijft wat elke routefamilie accepteert en de exacte foutmeldingen die u dan ziet.

---

Wat contextId identificeert

Routefamilie	contextId accepteert
/v1/twin/{contextId}/... (space, assets, POI’s, zones, concepten, business objects, embed-sessies)	Een twin-id, het id van de site waartoe de twin behoort, of het id van een van de concepten
/v1/reality-plan/{contextId}/... (space, layouts, bundles, model assets)	Een RealityPlan Project-id, of het id van een van de layouts

De twee families sluiten elkaar uit: een twin-route lost alleen twin-vormige id’s op, en een RealityPlan-route lost alleen projectvormige id’s op.

Een geldig id van het verkeerde type: 404, geen 400

Een correct gevormd id dat bij de andere familie hoort, faalt niet bij validatie: het wordt opgelost naar een echte context, alleen niet een die deze route bedient. De API antwoordt met 404 Not Found en een bericht dat aangeeft wat de route wél bedient:

{
  "statusCode": 404,
  "message": "This route serves twins. It accepts a twin id, the id of the site it belongs to, or the id of one of its drafts.",
  "error": "Not Found"
}

{
  "statusCode": 404,
  "message": "This route serves design projects. It accepts a design project id or the id of one of its layouts.",
  "error": "Not Found"
}

Sommige routes voegen een hint toe die verwijst naar de tegenhanger-route die het andere type wél bedient. GET /v1/twin/{contextId}/space voegt bijvoorbeeld toe:

This route serves twins. It accepts a twin id, the id of the site it belongs to, or the id of one of its drafts. The composition of a design project or a layout is served by GET /v1/reality-plan/{contextId}/space.

en GET /v1/reality-plan/{contextId}/space voegt het spiegelbeeld toe:

This route serves design projects. It accepts a design project id or the id of one of its layouts. The composition of a twin or a twin draft is served by GET /v1/twin/{contextId}/space.

Niet elke route heeft een tegenhanger. Assets, POI’s, zones, concepten en business object-zoeken bestaan alleen voor twins, en model assets en layouts bestaan alleen voor RealityPlan Project; die routes bevatten geen hint, alleen het basisbericht over wat ze bedienen.

Opmerking

Het antwoord bij het verkeerde type is altijd 404, nooit 400: het id zelf is geldig, het is alleen niet adresseerbaar op die route. Behandel het net als elk ander “niet gevonden op deze route”.

Een contextId dat geen UUID is: 400

Als contextId helemaal geen UUID is, wijst de API het af nog vóórdat het een route-handler bereikt:

{
  "statusCode": 400,
  "message": "Context ID must be a UUID",
  "error": "Bad Request"
}

Deze controle gebeurt vóór de standaard requestvalidatie, dus dit is het bericht dat u ziet bij een onjuist gevormde contextId, ongeacht welke routefamilie u aanroept.

Het juiste id vinden

Werk vanaf GET /oauth/api-info via GET /v1/nodes/{id}/browse de hiërarchie af om een twin-, site-, concept-, project- of layout-id te vinden: zie Finding Your IDs voor de volledige uitleg. Zodra u een id heeft, laat deze pagina zien welke routefamilies dat id ontgrendelt.