Richieste, metodi e risposte ============================= .. _http_request: Richieste HTTP ++++++++++++++ Le API di GestionaleAuto.com comunicano utilizzando il protocollo HTTP e utilizzano |json_link|_ come formato di input [#inputformat]_. Ogni chiamata viene eseguita su un *entry point* del tipo: .. code-block:: python /// 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 :ref:`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 .. note:: 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**: .. code-block:: javascript Content-type: application/json Se 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_risposta_http: 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*. |br| Le API utilizzano i seguenti metodi [#inputmethodformat]_: +------------+--------------------------------------------------------+ | 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 [#responseformat]_, vi sono dei casi particolari che possono essere generalizzati. Gli errori **404** e **500**, ad esempio, forniscono un risultato JSON del tipo: .. code-block:: javascript { "error": "error message" } Dove il campo ``error`` contiene un messaggio che indica il motivo dell'errore. .. [#inputformat] In ogni *entry point* delle API è specificato il formato *JSON* di input. .. [#inputmethodformat] In ogni *entry point* delle API è specificato il metodo da utilizzare .. [#responseformat] In ogni *entry point* delle API è specificato il formato della risposta ottenuto .. This is a workaround to have line break, see: http://docutils.sourceforge.net/FAQ.html#how-to-indicate-a-line-break-or-a-significant-newline .. |br| raw:: html
.. Since RST does not allow nested tags, to have a link with formatting you must use this workaround see: https://stackoverflow.com/questions/10669099/italicize-text-containing-a-link .. _json_link: http://www.json.org .. |json_link| replace:: *JSON*