Was contextId akzeptiert

contextId ist ein erforderlicher Pfadparameter auf jeder /v1/twin/{contextId}/...- und /v1/reality-plan/{contextId}/...-Route. Er ist polymorph: mehrere unterschiedliche Id-Typen werden darüber aufgelöst, weshalb eine wohlgeformte UUID trotzdem 404 zurückgeben kann. Diese Seite beschreibt, was jede Routenfamilie akzeptiert und welche Fehler dabei genau auftreten.

---

Was contextId identifiziert

Routenfamilie	contextId akzeptiert
/v1/twin/{contextId}/... (Space, Assets, POIs, Zonen, Entwürfe, Geschäftsobjekte, Embed-Sitzungen)	Eine Twin-Id, die Id der Site, zu der der Twin gehört, oder die Id eines seiner Entwürfe
/v1/reality-plan/{contextId}/... (Space, Layouts, Bundles, Modell-Assets)	Eine RealityPlan Project-Id, oder die Id eines ihrer Layouts

Die beiden Familien schließen sich gegenseitig aus: Eine Twin-Route löst nur Twin-förmige Ids auf, eine RealityPlan-Route nur projektförmige Ids.

Eine gültige Id der falschen Art: 404, nicht 400

Eine wohlgeformte Id, die zur jeweils anderen Familie gehört, schlägt nicht bei der Validierung fehl: sie wird zu einem echten Kontext aufgelöst, nur eben nicht zu einem, den diese Route bedient. Die API antwortet mit 404 Not Found und einer Nachricht, die benennt, was die Route tatsächlich 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"
}

Manche Routen hängen einen Hinweis an, der auf die Gegenstück-Route verweist, die die jeweils andere Art bedient. GET /v1/twin/{contextId}/space hängt zum Beispiel an:

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.

und GET /v1/reality-plan/{contextId}/space hängt das Spiegelbild an:

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.

Nicht jede Route hat ein Gegenstück. Assets, POIs, Zonen, Entwürfe und die Geschäftsobjekt-Suche existieren nur für Twins, Modell-Assets und Layouts nur für RealityPlan Projects; diese Routen tragen keinen Hinweis, nur die Basisnachricht dazu, was sie bedienen.

Hinweis

Die Antwort auf die falsche Art ist ein 404, niemals ein 400: Die Id selbst ist gültig, sie ist nur auf dieser Route nicht adressierbar. Behandeln Sie sie wie jedes andere “auf dieser Route nicht gefunden”.

Eine contextId, die keine UUID ist: 400

Ist contextId überhaupt keine UUID, weist die API sie ab, bevor sie einen Route-Handler erreicht:

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

Diese Prüfung erfolgt vor der Standard-Anfragevalidierung, weshalb dies die Nachricht ist, die Sie für eine fehlerhafte contextId unabhängig von der aufgerufenen Routenfamilie sehen.

Die richtige Id finden

Arbeiten Sie sich von GET /oauth/api-info über GET /v1/nodes/{id}/browse durch die Hierarchie, um eine Twin-, Site-, Entwurfs-, Projekt- oder Layout-Id zu finden: die vollständige Anleitung dazu finden Sie unter Finding Your IDs. Sobald Sie eine Id haben, sagt Ihnen diese Seite, welche Routenfamilien sie freischaltet.