Richieste, metodi e risposte¶
Richieste HTTP¶
Le API di GestionaleAuto.com comunicano utilizzando il protocollo HTTP e utilizzano JSON come formato di input [1].
Ogni chiamata viene eseguita su un entry point del tipo:
/<version>/<user_id>/<entry_point>
dove:
- version è la versione delle API che viene invocata. Attualmente il valore da inserire è
v2 - user_id è l’identificativo univoco dell’utente di GestionaleAuto.com su cui si desidera operare. Il vostro token di autorizzazione può essere associato a uno o più utenti di GestionaleAuto.com, in questo modo si indica su quale utente si vuole operare
- entry point è l’identificativo della risorsa su cui si desidera operare
Nota
Affinché le API possano elaborare il contenuto della richiesta nel formato JSON è necessario aggiungere l”header che informa il server dell’utilizzo di tale formato.
Ogni chiamata deve contenere l’header:
Content-type: application/jsonSe alcune chiamate utilizzeranno un content-type diverso, sarà indicato nella documentazione dell”entry point.
Le risposte utilizzano i codici standard di risposta HTTP e JSON per produrre risorse che possono essere utilizzate dalla logica dei client delle API.
Codici di risposta HTTP¶
Normalmente i significati dei codici di risposta HTTP seguono il seguente modello:
| Codice di risposta HTTP | Significato |
|---|---|
| 2xx | La richiesta è stata ricevuta correttamente, compresa e accettata |
| 4xx | Si è verificato un errore nella richiesta (solitamente un parametro errato dal client) |
| 5xx | Si è verificato un errore sul server (in questo caso contattate GestionaleAuto.com) |
Nel dettaglio, le API definiscono questi codici di risposta
| Codice di risposta HTTP | Significato |
|---|---|
| 200 | Richiesta ricevuta, compresa ed evasa correttamente |
| 201 | Indica che la risorsa è stata creata correttamente a seguito della richiesta |
| 202 | Lavoro accettato, per la produzione asincrona |
| 204 | Lavoro asincrono completato |
| 400 | Parametri non corretti |
| 401 | Errore di autenticazione |
| 403 | Accesso alla risorsa negato (permessi non sufficienti) |
| 404 | Risorsa non trovata |
| 405 | Metodo non valido |
| 409 | Conflitto, tentativo di modificare una risorsa che non si trova nello stato corretto |
| 500 | Errore generico sul server (in questo caso contattate GestionaleAuto.com) |
| 501 | Richiesta non ancora implementata |
| 503 | Servizio non disponibile (manutenzione o carico eccessivo) |
| 504 | Richiesta in timeout (in questo caso contattate GestionaleAuto.com) |
Significato dei metodi utilizzati¶
I metodi utilizzati dai client esprimono le operazioni che si desidera effettuare sfruttando l”entry point.
Le API utilizzano i seguenti metodi [2]:
| Metodo | Significato |
|---|---|
| GET | Lettura dei dati di una risorsa |
| POST | Creazione di una risorsa |
| PUT | Modifica di una risorsa (inviando tutto il set di dati) |
| PATCH | Modifica di una parte di una risorsa |
| DELETE | Cancellazione di una risorsa |
Risposte JSON¶
Sebbene ogni entry point definisca un formato di risposta personalizzato [3], vi sono dei casi particolari che possono essere generalizzati. Gli errori 404 e 500, ad esempio, forniscono un risultato JSON del tipo:
{
"error": "error message"
}
Dove il campo error contiene un messaggio che indica il motivo dell’errore.
| [1] | In ogni entry point delle API è specificato il formato JSON di input. |
| [2] | In ogni entry point delle API è specificato il metodo da utilizzare |
| [3] | In ogni entry point delle API è specificato il formato della risposta ottenuto |