REST API
========

La piattaforma **Radar-DPC** include uno stack di servizi Representational State Transfer (REST), utilizzati nel back end dagli applicativi, ma che rappresenta 
anche utile API (Applicatio Program Interface) per il download dei dati Radar e più in generale 
per il lavoro con i servizi esposti da parte di applicazioni di terze parti. 

WADL e metodi
-------------

L'insieme delle operazioni disponibili tramite la API è descritto nel documento WADL (Web Application Description Language).

Il punto di accesso al WADL è:

.. code-block:: html

        https://radar-api.protezionecivile.it/

Ispezionando il WADL è possibile notare i seguenti metodi:

+--------------------------------+--------+-------------------------------------------------------------------------------------------------------+
| Resurche Path                  | Metodo | Descrizione                                                                                           |
+================================+========+=======================================================================================================+
| /product/findAvailableProducts   | GET    | Restituisce la lista dei prodotti disponibili (types)                                                 |
+--------------------------------+--------+-------------------------------------------------------------------------------------------------------+
| /product/findLastProductByType | GET    | Restituisce il timestamp dell'ultima acquisizione per il prodotto specificato                         |
+--------------------------------+--------+-------------------------------------------------------------------------------------------------------+
| /product/existsProduct         | GET    | Verifica se esiste una acquisizione del prodotto specificato al timestamp specificato                 |
+--------------------------------+--------+-------------------------------------------------------------------------------------------------------+
| /product/downloadProduct       | POST   | Richiede il download dell'acquisizione del prodotto specificato al timestamp specificato              |
+--------------------------------+--------+-------------------------------------------------------------------------------------------------------+
| /product/watchProductDir 	 | GET 	  | Utilizzato dal back-end per monitorare la presenza di una nuova acquisizione del prodotto specificato |
+--------------------------------+--------+-------------------------------------------------------------------------------------------------------+


Esempi di richieste
-------------------

Si riportano di seguito alcuni esempi di richieste alla API REST, con relativa risposta da parte del servizio.

findAvailableProducts
^^^^^^^^^^^^^^^^^^^^^

Il metodo non richiede nessun parametro di input

.. code-block:: html

	https://radar-api.protezionecivile.it/wide/product/findAvailableProducts


Il servizio risponde con un json come il seguente, che include il numero dei prodotti disponibili ( *total* ) e la lista dei nomi di tali prodotti ( *types* ).

.. code-block:: html

	{
 	 "total" : 18,
	 "types" : [ "CAPPI4", "CAPPI6", "CAPPI8", "SRT6", "CAPPI2", "VMI", "HRD", "CAPPI5", "TEMP", "SRT1", "SRT3", "RADAR_STATUS", "CAPPI7", "SRT24", "CAPPI1", "SRI", "CAPPI3", "SRT12" ]
	}


findLastProductByType
^^^^^^^^^^^^^^^^^^^^^

Per questo metodo è necessario valorizzare il parametro di input *type*, assegnando uno dei valori presenti nella lista restituita dal servizio precedentemente presentato.
Ad esempio:


.. code-block:: html

	https://radar-api.protezionecivile.it/wide/product/findLastProductByType?type=VMI

dove con l'apposizione della stringa "*?type=VMI*" si sta specificando il prodotto VMI.

Il servizio risponde con un json come quello mostrato di seguito

.. code-block:: html

	{
  	 "total" : 1,
 	 "lastProducts" : [ {
   	 "productType" : "VMI",
   	 "time" : 1640160600000,
   	 "period" : "PT5M"
 	 } ]
	}

Il quale riporta il timestamp UTC in millisecondi ("*time*") dell'ultima acquisizione disponibile per il prodotto VMI. Il json riporta inoltre la periodicità di acquiszione ("*period*"), nell'esempio, il prodotto AMV è disponibile ogni 5  minuti.


existsProduct
^^^^^^^^^^^^^

Il servizio necessita di due paramentri di ingresso, *type* e *time* indicanti rispettivamente il tipo di prodotto e il timestamp UTC in millisecondi per il quale si voglia verificare la presenza o meno dell'acquisizione.


.. code-block:: html

	https://radar-api.protezionecivile.it/wide/product/existsProduct?type=VMI&time=16401606000000

Il servizio risponde con valore booleano.


downloadProduct
^^^^^^^^^^^^^^^
Il servizio va invocato con metodo POST, passando in input un json indicante il tipo di prodotto e il timestamp UTC in millisecondi dell'acquisizione che si voglia scaricare.
Un esempio di json da utilizzare come input è il seguente: 


.. code-block:: html

	{
  	 "productType" : "HRD",
 	 "productDate" : 1594023197641
	}

Il servizio, a seconda del tipo di prodotto che si è richiesto, predispone l'output per il download. Nel caso di prodotti vettoriali (es. HRD) il servizio ritorna archivio contenente la collezione shapefile relativa al campione richiesto. Nel caso di raster (es. AMV) il servizio ritorna file con la copertura.

Di seguito, per scopi illustrativi, si mostra anche chiamata al servizio mediante utilità CUrl:

.. code-block:: html

	curl --data '{"productType":"HRD","productDate":"1572955800000"}' -H "Content-Type: application/json" -X POST https://radar-api.protezionecivile.it/wide/product/downloadProduct --output hrd.zip



.. toctree::
   :maxdepth: 2
   :caption: Contenuti