Documentazione
Convenzioni & errori
Le regole comuni a tutta l'API: indirizzi base, autenticazione, formato delle risposte, codici di stato e livelli di autorità.
Indirizzi base
Nei percorsi di questa documentazione, https://api.spectraholo.it è l'indirizzo dell'API server e https://auth.spectraholo.it quello dell'Auth server (usato solo per il login). I segnaposto tra graffe, come {orgId} o {viewerId}, vanno sostituiti con i valori reali.
Autenticazione
Quasi tutti gli endpoint richiedono un token utenteottenuto con il login, inviato a ogni richiesta nell'header:
Authorization: Bearer <token>
Alcuni endpoint sono pubblici(es. il logo o l'avatar) e non richiedono autenticazione. Vedi Autenticazione per ottenere e revocare un token.
Formato delle risposte
Le risposte JSON seguono una busta uniforme con il campo success; in caso di errore è presente un message leggibile.
Successo
{
"success": true,
"organization": { "id": 42, "name": "ACME" }
}Errore
{
"success": false,
"message": "Invalid or expired session."
}Codici di stato
| 200 · 201 | Operazione riuscita (201 quando viene creata una risorsa). |
| 400 | Richiesta non valida: corpo JSON malformato o campi non validi. |
| 401 | Autenticazione mancante o token non valido/scaduto. |
| 403 | Autenticato ma authority insufficiente per l'operazione. |
| 404 | Risorsa non trovata (organizzazione, utente, modello, viewer…). |
| 409 | Conflitto: es. username/email già in uso, viewer non in pairing. |
| 413 | Payload troppo grande: file oltre il limite o quota di storage superata. |
| 429 | Troppe richieste (es. tentativi di login): riprova più tardi. |
| 502 | Un servizio interno è momentaneamente irraggiungibile: riprova. |
Livelli di authority
Ogni utente ha un livello di autorità da 0 a 3. I livelli sono cumulativi: un livello include i permessi di quelli inferiori. Gli endpoint indicano l'authority minima richiesta.
| 0 | Lettura | Consulta organizzazione, membri, modelli e viewer. |
| 1 | Display | Decide cosa mostrano i viewer (assegna/azzera il modello). |
| 2 | Gestione | Accoppia/dissocia viewer e gestisce i modelli 3D. |
| 3 | Admin | Gestisce gli utenti e il profilo dell'organizzazione. |
Suggerimento