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

   /<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 :ref:`token di autorizzazione <token_def>` 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 <https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>`_ 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 <mailto:developers@gestionaleauto.com?subject=[API]%20Errore%20500%20sul%20server>`_) |
+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

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 <mailto:developers@gestionaleauto.com?subject=[API]%20Errore%20500%20sul%20server>`_) |
+-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **501**                 | Richiesta non ancora implementata                                                                                                                               |
+-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **503**                 | Servizio non disponibile (manutenzione o carico eccessivo)                                                                                                      |
+-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **504**                 | Richiesta in timeout (in questo caso contattate `GestionaleAuto.com <mailto:developers@gestionaleauto.com?subject=[API]%20Errore%20500%20sul%20server>`_)       |
+-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+

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

   <br />


.. 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*