Skip to content

API: v1

Jump to bottom Edit New page
Alfio Emanuele edited this page May 6, 2018 · 16 revisions

Introduzione

✏️ Questo documento è una bozza!

⚠️ Nota bene: Attualmente questa funzionalità è da considerarsi altamente sperimentale ed è disponibile solo sulla versione di sviluppo di Gaia, sul branch oauth. I contenuti di questa pagina non sono definitivi e sono aperti ai commenti: come tali, possono cambiare velocemente senza preavviso. Segui questa pagina per aggiornamenti sulla funzionalità.

Motivazione

Gaia espone delle API ai seguenti scopi:

  • [...] identificazione tramite Gaia;
  • [...] validazione del Comitato di appartenenza;
  • [...] ottenere un elenco aggiornato delle Sedi CRI.

Registrare una applicazione

Per utilizzare le API, è necessario registrare l'applicazione su Gaia.

E' possibile farlo recandosi all'URL:

/o/applications/

Cliccando quindi su "New Application" e seguendo le istruzioni per la creazione di una nuova applicazione. Il modulo va compilato come segue:

  • Name: Nome dell'applicazione. Questo verrà mostrato all'utente in fase di autorizzazione.
  • Client id e Client secret sono generati automaticamente. Copia questi valori.
  • Client type: Confidential.
  • Authorization grant type: Authorization code.
  • Redirect uris: Un elenco di URI accettati per il redirect in seguito all'autorizzazione, uno per riga. Quello primario (che verrà utilizzato quando il Client non specifica alcun URI) deve essere impostato nella prima riga.

Requisiti

Requisiti di sicurezza e trattamento dei dati degli utenti [...]

Autenticazione

L'autenticazione deve avvenire tramite OAuth 2.0. [...]

  • Auth URL (indirizzo di autorizzazione): 
    /o/authorize
  • Access Token URL (indirizzo di scambio di token): 
    /o/token

Scope

OAuth 2.0 prevede l'uso di scope [...]

La seguente tabella elenca gli scope disponibili e la loro descrizione (i dati a cui danno accesso).

Scope Descrizione
anagrafica_lettura_base Lettura dell'anagrafica di base della persona identificata: ID, nome, cognome e indirizzo email.
anagrafica_lettura_completa Lettura dell'anagrafica completa della persona identificata: anagrafica completa, più luogo e data di nascita, luogo di residenza, codice fiscale e sesso.
appartenenze_lettura Lettura delle appartenenze attuali della persona identificata.

Formato richieste

Le API sono REST e utilizzano il formato JSON (JavaScript Object Notation) (come da specifica su json.org). Il Content Type utilizzato per tutte le risposte è application/json.

Tipi

Campo

Il tipo Campo è un tipo generico che viene utilizzato per descrivere un attributo che può avere più valori. Questi valori hanno sia un componente identificativa breve (ad esempio, un codice specifico), che una descrizione leggibile per gli umani. Quando si incontra un attributo di questo tipo, la descrizione è da considerare variabile e non dovrebbe essere utilizzata per identificare un valore possibile.

Parametro Opz.? Tipo Descrizione
id No Stringa o Numero Una stringa che può essere utilizzata per identificare e discernere valori diversi.
descrizione Sì Stringa Una descrizione leggibile per questo valore, che può essere mostrata ad un utente (ma non dovrebbe essere utilizzata programmaticamente per discernere valori diversi, in quanto potrebbe variare).

Sede

Il tipo Sede si riferisce una Sede di Croce Rossa Italiana, rappresentata da un oggetto JSON con i seguenti attributi:

Parametro Opz.? Tipo Descrizione
nome No Stringa Il nome della Sede.
estensione No Campo L'estensione della Sede: "N" per Sede Nazionale; "R" per Sede Regionale; "P" per Sede Provinciale; "L" per Sede Locale; "T" per Unità Territoriale.
tipo Sì Campo Tipo della Sede. "C" per Comitato di Croce Rossa Italiana.
locazione Sì Luogo Locazione geografica della Sede.
comitato Sì Stringa Il Comitato a cui questa sede fa riferimento, nel caso in cui la Sede sia un distaccamento territoriale. Questo campo è sempre presente nel caso estensione sia uguale a "T" (Unità Territoriale).

Luogo

Il tipo Luogo si riferisce ad una località geografica (che può essere un comune, un indirizzo postale specifico, o qualsiasi cosa tra i due), rappresentata da un oggetto JSON con i seguenti attributi:

Parametro Opz.? Tipo Descrizione
comune No Stringa Il nome del comune (città o città ai fini postali).
stato No Stringa Stato espresso in formato a due lettere ISO 3166-1 alpha 2 (ad es., "IT")
via Sì Stringa Nome della strada. In caso di più componenti, questi sono separati da virgola.
civico Sì Stringa Numero civico o nome dell'abitazione ai fini postali.
provincia Sì Stringa Nome della provincia ai fini postali.
cap Sì Stringa Codice di avviamento postale (CAP, ZIP o simile).

Errori

In caso di errore, la risposta ricevuta avrà un codice di risposta HTTP diverso da 200 (200 OK).

Il corpo della risposta conterrà un oggetto JSON con un singolo attributo, detail, contenente una descrizione dell'errore riscontrato. Questa descrizione è una descrizione leggibile per gli umani e può cambiare: per riconoscere un errore in modo programmatico, è fondamentale fare affidamento sul codice di errore HTTP, piuttosto che su questo messaggio.

Permessi mancanti (403)

In caso di mancata autenticazione, o qualora lo scope necessario per una richiesta non sia stato concesso dall'utente, Gaia risponderà con un codice di errore HTTP 403 (403 Not Authorized).

Il corpo della risposta potrebbe assomigliare al seguente:

{
  "detail": "Non hai l'autorizzazione per eseguire questa azione."
}

Prefisso

Importante: Tutti i metodi elencati in questa pagina hanno un URL con il seguente prefisso:

/api/v1/

Ad esempio, per il metodo elencato sotto come /me/anagrafica/, è necessario utilizzare il seguente URL:

https://gaia.cri.it/api/v1/me/anagrafica/

Metodi

Ecco una tabella di tutti i metodi disponibili:

[...]

Verbo Metodo Scope
GET /me/anagrafica/base/ anagrafica_lettura_base
GET /me/anagrafica/completa/ anagrafica_lettura_completa
GET /me/appartenenze/attuali/ appartenenze_lettura

GET /me/anagrafica/base/

Questo metodo ottiene le informazioni anagrafiche basilari dell'utente identificato, che possono utilizzare a scopo di autenticazione.

Autenticazione

Questa richiesta necessita autenticazione tramite OAuth 2.0.

Richiesta

Questa richiesta non necessita di alcun parametro.

Risposta

Parametro Opz.? Tipo Descrizione
id No Numero Un numero intero positivo univoco che identifica la persona in Gaia.
nome_completo No Stringa Il nome completo della persona identificata
nome No Stringa Il nome della persone identificata.
cognome No Stringa Il cognome della persone identificata.
email Sì Stringa L'indirizzo email di contatto della persona identificata.

Scope necessari

  • anagrafica_lettura_base

Risposta di esempio

{
    "id": 3,
    "nome_completo": "Douglas Adams",
    "nome": "Douglas",
    "cognome": "Adams",
    "email": "supporto@gaia.cri.it"
}

GET /me/anagrafica/completa/

Autenticazione

Questa richiesta necessita autenticazione tramite OAuth 2.0.

Scope necessari

  • anagrafica_lettura_base
  • anagrafica_lettura_completa

Richiesta

Questa richiesta non necessita di alcun parametro.

Risposta

Parametro Opz.? Tipo Descrizione
id No Numero Un numero intero positivo univoco che identifica la persona in Gaia.
nome_completo No Stringa Il nome completo della persona identificata
nome No Stringa Il nome della persone identificata.
cognome No Stringa Il cognome della persone identificata.
email Sì Stringa L'indirizzo email di contatto della persona identificata.
luogo_di_nascita Sì Luogo Luogo di nascita della persona identificata.
luogo_di_residenza Sì Luogo Luogo di residenza della persona identificata.
sesso Sì Stringa Il sesso della persona identificata. Valori possibili: "M", "F".
codice_fiscale Sì Stringa Il codice fiscale della persona identificata.

Risposta di esempio

{
    "id": 3,
    "nome_completo": "Douglas Adams",
    "nome": "Douglas",
    "cognome": "Adams",
    "email": "supporto@gaia.cri.it",
    "luogo_di_nascita": {
        "comune": "arena po",
        "stato": "IT"
    },
    "luogo_di_residenza": {
        "comune": "velturno",
        "stato": "IT",
        "provicina": "ZZ",
        "cap": "00100",
        "indirizzo": "Via prova 34"
    },
    "sesso": "F",
    "codice_fiscale": "DMSDLS71L54A387U"
}

GET /me/appartenenze/attuali/

Autenticazione

Questa richiesta necessita autenticazione tramite OAuth 2.0.

Scope necessari

  • anagrafica_lettura_base
  • anagrafica_lettura_completa

Richiesta

Questa richiesta non necessita di alcun parametro.

Risposta di esempio

{
    "appartenenze": [
        {
            "inizio": "2005-08-12T22:45:59.984893",
            "fine": null,
            "tipo": {
                "id": "VO",
                "descrizione": "Volontario"
            },
            "sede": {
                "nome": "Comitato di Gaia",
                "estensione": {
                    "id": "L",
                    "descrizione": "Sede Locale"
                },
                "tipo": {
                    "id": "C",
                    "descrizione": "Comitato"
                },
                "comitato": {
                    "nome": "Comitato di Gaia",
                    "estensione": {
                        "id": "L",
                        "descrizione": "Sede Locale"
                    },
                    "tipo": {
                        "id": "C",
                        "descrizione": "Comitato"
                    }
                }
            }
        }
    ]
}
Add a custom footer

Concetti base

Moduli di Gaia

API (v1)

Clone this wiki locally