Come iniziare

Formato Risposte

Formato standardizzato delle risposte API

Tutte le risposte dell'API seguono uno schema standardizzato per garantire coerenza e prevedibilità.

Schema Base

Risposta di Successo

{
  "status": "success",
  "data": <dati della risposta>,
  "meta": {
    "requestId": "uuid-unico-della-richiesta",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Risposta di Errore

{
  "status": "error",
  "error": {
    "code": "CODICE_ERRORE",
    "message": "Messaggio di errore descrittivo",
    "details": {}
  },
  "meta": {
    "requestId": "uuid-unico-della-richiesta",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Campi della Risposta

status

Indica l'esito della richiesta:

  • "success" - Richiesta completata con successo
  • "error" - Si è verificato un errore

data

Contiene i dati della risposta quando status è "success". Può essere:

  • Un oggetto singolo
  • Un array di oggetti
  • Un valore primitivo

error

Presente solo quando status è "error". Contiene:

  • code: Codice errore standardizzato
  • message: Messaggio descrittivo dell'errore
  • details: Oggetto con dettagli aggiuntivi (opzionale)

meta

Metadati della richiesta:

  • requestId: UUID univoco per tracciare la richiesta
  • timestamp: Timestamp ISO 8601 della risposta

Esempi Pratici

Risposta Singola Risorsa

{
  "status": "success",
  "data": {
    "id": 123,
    "name": "Esempio Organizzazione",
    "tax_code": "12345678901",
    "created_at": "2024-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Risposta Collezione con Paginazione

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "Organizzazione 1"
    },
    {
      "id": 2,
      "name": "Organizzazione 2"
    }
  ],
  "meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "total": 100,
    "limit": 10,
    "offset": 0,
    "page": 1,
    "totalPages": 10
  }
}

Risposta di Errore

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "I dati forniti non sono validi",
    "details": {
      "email": "Email non valida",
      "password": "Password deve contenere almeno 8 caratteri"
    }
  },
  "meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Codici di Stato HTTP

L'API utilizza i codici di stato HTTP standard:

CodiceSignificatoQuando
200OKRichiesta completata con successo
201CreatedRisorsa creata con successo
204No ContentOperazione completata senza contenuto
400Bad RequestRichiesta malformata o non valida
401UnauthorizedAutenticazione richiesta o non valida
403ForbiddenAccesso negato (autorizzazione)
404Not FoundRisorsa non trovata
409ConflictConflitto con stato attuale
422Unprocessable EntityValidazione fallita
500Internal Server ErrorErrore interno del server
503Service UnavailableServizio temporaneamente non disponibile

Gestione Errori

Per maggiori dettagli sulla gestione degli errori, consulta:

Best Practices

  1. Sempre controlla status prima di accedere a data
  2. Usa requestId per tracciare problemi in produzione
  3. Gestisci tutti i codici di stato HTTP appropriatamente
  4. Mostra message all'utente per errori user-friendly
  5. Usa details per validazione form e debugging

Note Tecniche

  • Tutte le date sono in formato ISO 8601
  • I numeri sono sempre rappresentati come numeri JSON (non stringhe)
  • I valori null sono esplicitamente rappresentati (non omessi)
  • Gli array vuoti sono rappresentati come [] (non null)