API

(Documentazione completa: http://docs.ckan.org/en/latest/api/index.html )

Le API di CKAN sono un potente strumento che espone tutte le funzionalità del core di CKAN a chiunque le usi. Sono uno strumento essenziale per chi vuole sviluppare app sui dati presenti sul sito.

Ecco qualche esempio delle potenzialità di queste API:

Lista delle categorie presenti sul sito: http://opendata.comune.civitavecchia.rm.it/api/3/action/group_list
Lista dei dataset presenti sul sito: http://opendata.comune.civitavecchia.rm.it/api/3/action/package_list

Fare una request tramite API

Per fare una chiamata alle API di CKAN, controlla che tipo di request deve essere effettuata (HTTP POST o HTTP GET), ed invia i parametri correttamente. La risposta di CKAN si presenterà nel formato JSON. Per esempio, per prendere la lista dei nomi di tutti i dataset contenuti nella categoria anagrafica, chiama la funzione API group_list con il comando curl da un terminale:

curl http://opendata.comune.civitavecchia.rm.it/api/3/action/group_list -d '{"id"="anagrafica"}'

La risposta di CKAN sarà simile a questa:

                    {
    "help": "...",
    "result": [
        "data-explorer",
        "department-of-ricky",
        "geo-examples",
        "geothermal-data",
        "reykjavik",
        "skeenawild-conservation-trust"
    ],
    "success": true
}
                

La risposta è un JSON dictionary con tre chiavi:

"success": true o false.

Le API ritornano sempre 200 OK come status code della loro risposta HTTP, anche se ci sono stati errori con la richiesta. E' quindi importante controllare il valore di "success" nella risposta e, se 'success' è false, controllare il valore di error

"result": il risultato della funzione che hai chiamato. Il tipo ed il valore del risultato dipendono da quale funzione hai chiamato. Nel caso della funzione group_list il tipo è una lista di stringhe, i nomi di tutti i dataset che appartengono a quel gruppo.

Se c'è stato un errore rispondendo alla richiesta, il JSON conterrà una chiave "error" con i dettagli dell'errore invece della chiave "result". Una risposta che contiene un errore sarà simile a questa:
```
{
    "help": "Creates a package",
    "success": false,
    "error": {
        "message": "Access denied",
        "__type": "Authorization Error"
        }
 }
```
"help": la stringa che documenta la funzione che è stata chiamata.

Versioni delle API

Le API di CKAN hanno diverse versioni. Se si vuole effettuare una richiesta ad un API tramite URL senza specificare la versione, CKAN scegliere automaticamente l'ultima versione dell'API chiamata:

http://opendata.comune.civitavecchia.rm.it/api/action/package_list

Alternativamente, è possibile specificare il numero della versione dell'API desiderata nell'URL che si richiede:

http://opendata.comune.civitavecchia.rm.it/api/3/action/package_list

La versione 3 è momentaneamente l'unica versione delle API di tipo Action.

La raccomandazione è quella di specificare il numero della versione nelle proprie request, perchè questo assicura che il client che effettua le chiamate API funzionaerà in diversi siti che usano diverse versioni di CKAN.

Funzioni API richiamabili tramite GET

Le funzioni definite in ckan.logic.action.get possono essere chiamate tramite una richiesta HTTP GET Per esempio, per ricevere la lista dei dataset dal sito, si può inserire nell'URL del browser:

http://opendata.comune.civitavecchia.rm.it/api/3/action/package_list

Oppure, per cercare i dataset che contengono la parola spending, clicca su questo link:

http://opendata.comune.civitavecchia.rm.it/api/3/action/package_search?q=spending

La query di ricerca è passata come un parametro URL ?q=spending. E' possibile usare diversi paramentri URL, separati dal carattere&, per sempio per prendere solo i primi 10 dataset della ricerca, apri questo URL:

http://opendata.comune.civitavecchia.rm.it/api/3/action/package_search?q=spending&rows=10

Quando un'azione richiede una lista di stringhe come valore del parametro, il valore può essere inviato semplicemente inserendo il parametro diverse volte nell'URL:

http://opendata.comune.civitavecchia.rm.it/api/3/action/package_search?q=nascite&q=registro&rows=10

Funzioni API gestione utenti

Vi sono due funzioni non definite in ckan.logic.action.get richiamabili tramite API sul portale di Civitavecchia: ckan.logic.action.update.user_update e ckan.logic.action.create.user_create. Per usufruire di queste funzioni, bisogna usare una request di tipo POST. Ad esempio, potremmo usare il comando curl da console:

curl http://opendata.comune.civitavecchia.rm.it/api/3/action/user_create -d '{ "name":"nome_utente", "email": "email_utente", "password": "PWD" }'

In questo modo viene passato correttamente il dict JSON richiesto dalla funzione.