Guida rapida per l'utente - AgID/rndt-geodcat-ap-api GitHub Wiki
L'API di RNDT per l'implementazione di GeoDCAT-AP consente di trasformare i metadati dei dati documentati secondo il profilo italiano, dallo standard ISO TS 19139 allo standard DCAT-AP/DCAT-AP_IT (estensione italiana di DCAT-AP) utilizzato per i dati aperti.
L'API accetta sia richieste CSW (GET e POST) che richieste REST e restituisce i metadati in formato RDF/XML o JSON-LD.
Istruzioni per l'utilizzo
Di seguito alcune istruzioni su come utilizzare l'API.
Sezione superiore: richieste GET
La sezione consente di inserire una richiesta nell'area di testo e di impostare i parametri riportati nella seguente tabella (tra parentesi il valore da utilizzare nell'URL dell'API che appare nell'area di testo inferiore).
| Parametro | Descrizione | Valori possibili | Note |
|---|---|---|---|
| Trasformazione di output (outputTranformation) | Il profilo da utilizzare per la trasformazione. | GeoDCAT-AP_IT (geodcatap_it) | comprende la codifica per tutti i metadati. |
| DCAT-AP_IT (dcatap_it) | comprende la codifica dei soli metadati che hanno una corrispondenza con le proprietà di DCAT-AP_IT | ||
| GeoDCAT-AP (extended) | comprende la codifica per tutti i metadati con riferimento a INSPIRE e il core ISO 19115 (non include quindi le estensioni italiane) | ||
| DCAT-AP (core) | comprende la codifica dei soli metadati che hanno una corrispondenza con le proprietà di DCAT-AP (non include quindi le estensioni italiane). | ||
| Formato di input (inputFormat) | Tipo di richiesta con riferimento all'interfaccia. | CSW | |
| REST | |||
| Formato di output (outputFormat) | Formato dei dati restituiti dall'API | RDF/XML (xml) | |
| JSON-LD (json) |
Richiesta CSW GET
- Inserire nell'area di testo l'URL di una richiesta CSW che restituisce record di tipo ISO 19139 e impostare i parametri come indicato innanzi.
- Premere, quindi, il tasto Trasforma.
NOTE
La tipologia di richiesta CSW supportata è solo GetRecords.
È necessario che nella richiesta CSW sia indicato il seguente schema di output (parametro outputSchema) http://www.isotc211.org/2005/gmd
Richiesta REST
Le richieste REST ammesse sono quelle coerenti con le API del RNDT. Informazioni utili per la composizione delle richieste REST sono disponibili nella pagina dedicata alle API REST.
I passi da seguire per l'utilizzo dell'API GeoDCAT-AP con le richieste REST sono i seguenti:
- Inserire nell'area di testo la richiesta REST senza includere il server (es. http://geodati.gov.it/RNDT/rest/find/document) e impostare i parametri come indicato innanzi. In questo caso, i valori ammissibili per il parametro "Trasformazione di output" sono solo "GeoDCAT-AP_IT" o "DCAT-AP_IT".
- Premere, quindi, il tasto Trasforma.
In alternativa, è possibile ottenere l'URL della richiesta REST dalla pagina della ricerca dettagliata seguendo i seguenti passi:
- Impostare i criteri di ricerca di interesse;
- Cliccare sul tasto "Anteprima";
- Nell'elenco dei risultati, cliccare sull'icona che appare in alto a destra;
- Copiare l'URL della richiesta;
- Decodificare l'URL utilizzando appositi tool (per es. l'URL encoder/decoder disponibile qui: https://meyerweb.com/eric/tools/dencoder/);
- Copiare la richiesta decodificata e incollare solo la parte dell'URL dopo il simbolo "?" nell'area di testo.
URL della richiesta GeoDCAT-AP
A prescindere dal tipo di richiesta (CSW o REST), nell'area di testo inferiore, viene reso disponibile l'URL della richiesta all'API GeoDCAT-AP avente il formato riportato nell'esempio seguente:
https://geodati.gov.it/geodcat-ap_it/index.php?outputTransformation=dcatap_it&inputFormat=CSW&outputFormat=JSON&src=...
Nell'URL è presente un altro parametro, src, non riportato nella tabella di cui sopra. Esso contiene la richiesta (CSW o REST), inserita nell'area di testo.
Sezione inferiore: richieste POST
- Inserire nell'area di testo la richiesta CSW POST e impostare i parametri come indicato per la sezione superiore. Anche in questo caso, i valori ammissibili per il parametro "Trasformazione di output" sono solo "GeoDCAT-AP_IT" o "DCAT-AP_IT". Non compare, inoltre, il parametro "Formato di input" in quanto l'unico valore possibile sarebbe "CSW".
- Premere il tasto Trasforma.
NOTA
Come per il metodo GET, la tipologia di richiesta CSW supportata è solo GetRecords.
Anche in questo caso, è necessario che nella richiesta CSW sia indicato il seguente schema di output (parametro outputSchema) http://www.isotc211.org/2005/gmd