Cosa accetta contextId

contextId è un parametro di percorso obbligatorio su ogni route /v1/twin/{contextId}/... e /v1/reality-plan/{contextId}/.... È polimorfo: diversi tipi di id vi si risolvono, il che spiega perché un UUID ben formato possa comunque restituire 404. Questa pagina descrive cosa accetta ciascuna famiglia di route e gli errori esatti che vedrete quando non corrisponde.

---

Cosa identifica contextId

Famiglia di route	contextId accetta
/v1/twin/{contextId}/... (space, assets, POI, zone, bozze, oggetti di business, sessioni embed)	Un id di twin, l’id del site a cui appartiene il twin, o l’id di una delle sue bozze
/v1/reality-plan/{contextId}/... (space, layout, bundle, model assets)	Un id di RealityPlan Project, o l’id di uno dei suoi layout

Le due famiglie si escludono a vicenda: una route twin risolve solo id a forma di twin, e una route RealityPlan risolve solo id a forma di progetto.

Un id valido del tipo sbagliato: 404, non 400

Un id ben formato appartenente all’altra famiglia non fallisce la validazione: viene risolto in un contesto reale, semplicemente non uno servito da questa route. L’API risponde con 404 Not Found e un messaggio che indica cosa serve davvero la route:

{
  "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"
}

Alcune route aggiungono un suggerimento che rimanda alla route omologa che serve l’altro tipo. Ad esempio, GET /v1/twin/{contextId}/space aggiunge:

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.

e GET /v1/reality-plan/{contextId}/space aggiunge il suo speculare:

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.

Non tutte le route hanno un’omologa. Assets, POI, zone, bozze e la ricerca di oggetti di business esistono solo per i twin, mentre model assets e layout esistono solo per i RealityPlan Project; queste route non riportano alcun suggerimento, solo il messaggio base su cosa servono.

Nota

La risposta per il tipo sbagliato è sempre 404, mai 400: l’id in sé è valido, semplicemente non è indirizzabile su quella route. Trattatelo come qualsiasi altro “non trovato su questa route”.

Un contextId che non è un UUID: 400

Se contextId non è nemmeno un UUID, l’API lo rifiuta prima ancora che raggiunga un handler di route:

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

Questo controllo avviene prima della validazione standard della richiesta, quindi è il messaggio che vedrete per un contextId malformato, indipendentemente dalla famiglia di route chiamata.

Trovare l’id giusto

Scendete da GET /oauth/api-info attraverso GET /v1/nodes/{id}/browse per trovare un id di twin, site, bozza, progetto o layout: consultate Finding Your IDs per il percorso completo. Una volta ottenuto un id, questa pagina indica quali famiglie di route sblocca.