API

Le API di Gaia

Documento aggiornato al 4 gennaio 2013.

QUESTO DOCUMENTO DESCRIVE LA VERSIONE DELLE API ATTUALMENTE IN PRODUZIONE. Per ulteriori informazioni, contattare [email protected].

Questo documento descrive le API di Gaia, la modalita' di accesso, i metodi disponibili e la licenza d'uso dei dati che ogni applicazione deve rispettare.

PER ULTERIORI INFORMAZIONI E DOCUMENTAZIONE, CONTATTA [email protected].

Ottenere accesso alle API di Gaia

Se desideri ottenere accesso alle API di Gaia avrai bisogno di una API KEY. Per ottenere una API KEY, contattaci a [email protected] con una descrizone del tuo progetto, dei dati che necessiti ed una stima di traffico generato dalla tua applicazione. Saremo felici di aiutarti.

Licenza d'uso dei dati

Usando le API di Gaia si accetta la licenza d'uso per i dati ottenuti.

E' per noi molto importante che sia chiara nella sua interezza a chiunque usi le API di Gaia al fine di garantire sicurezza e privacy agli utenti del sistema.

Punto di accesso

Le API sono accessibili tramite HTTPS (solo con SSL) tramite richiesta di tipo POST a:

https://gaia.cri.it/api.php

Tutti i dati vengono ricevuti ed inviati usando la notazione JSON.

Parametri della richiesta

Ogni richiesta effettuata alle API deve contenere un oggetto con almeno due parametri:

1. metodo contenente il metodo richiesto;
2. sid contenente l'ID della sessione attuale:

• Prima richiesta: non necessario, verra' assegnato dal sistema.
• Tutte le altre: deve essere impostato all'ultimo valore della stringa ricevuta da sessione.id.

3. key contiene l'API KEY che hai ricevuto da noi

{
  "metodo": "volontario",
  "sid":    "cb7989a10f359b7cbe2049862eed9ed4bbdb69f1181",
  "key":    "e2049862eed9ed4bbdb69f1181cb7989a1110bbdb69",
  <parametri>
}

Formato della risposta

Ogni risposta avra' un formato simile in caso di successo:

{
  "richiesta":   {
    "metodo":       <metodo>,
    "parametri":    { <parametri> },
    "data":         "20140102T020042Z0000"
  },
  "sessione":    { 
    "id":           "cb7989a10f359b7cbe2049862eed9ed4bbdb69f1181",
    "identificato": true,
    "utente":       {
      "id":           218,
      "nome":         "Alfio Emanuele",
      "cognome":      "Fresta"
    }
  },
  "tempo": 0.00690,
  "risposta": {
    <risposta>
    // "errore": { ... }
  },
}

• richiesta contiene i dati della richiesta ricevuta
  • richiesta.metodo e' una stringa che contiene il nome del metodo ricevuto
  • richiesta.parametri e' un oggetto contenente i parametri della richiesta
  • richiesta.data e' il timestamp, formato ISO 8601, della ricezione della richiesta
• sessione contiene i dati relativi all'utente identificato ed alla sessione
  • sessione.id contiene un codice unico della sessione attuale. NOTA: Questo deve essere usato come parametro sid della successiva richiesta
  • sessione.identificato e' un flag booleano che verifica se l'utente e' identificato o meno (anonimo)
  • sessione.utente, se l'utente e' anonimo, e' null, altrimenti oggetto con:
    • sessione.utente.id codice dell'utente attuale
    • sessione.utente.nome nome dell'utente attuale
    • sessione.utente.cognome cognome dell'utente attuale
• tempo e' il tempo di risposta delle API in millisecondi
• risposta e' l'oggetto che contiene la risposta del server
• risposta.errore e' presente quando la richiesta non e' valida o ha generato un errore:
  • risposta.errore.codice contiene il numero di errore
  • risposta.errore.messaggio contiene un messaggio descrittivo dell'errore

Chiamate

Questa sezione non e' completa. Per testare le API, e' consigliato usare la Console (F12 -> Console) di Google Chrome, con la seguente funzione. Nota, viene ereditata ed usata la sessione dell'utente in browser.

api( stringa NomeMetodo, oggetto parametri, funzione callback );

Esempio:

api(
    'attivita',
    {
        inizio: '2013-12-16T00:00:00.000Z',
        fine:   '2013-12-20T00:00:00.000Z'
    },
    function(x){
        console.log(x);
    }
);

Rubrica chiamate

• Login e logout
• Elenco altri metodi

Alcuni metodi non sono documentati. Per favore contattateci ad [email protected].