vai al contenuto principale

Servizi REST

La Cloudlet espone dei servizi REST che permettono di amministrarne gli utenti.

Le Cloudlet Livebase espongono una serie di endpoint REST che consentono di gestire i token di autenticazione JWT (utilizzabili per effettuare richieste a servizi dela Cloudlet esposti sotto il path auth) e gli utenti della Cloudlet senza bisogno di accedere a un front-end. Tutti gli endpoint accettano richieste di tipo OPTIONS allo scopo di restituire informazioni come l’insieme di metodi HTTP effettivamente supportati o i valori ammessi per gli header, e possono essere interrogati attraverso diverse utility quali cURL o Postman.

Le API REST accettano richieste e risposte nei formati XML e JSON, ed è possibile scegliere tra i due definendo il parametro format nella query string dell’URL, con un valore xml o json.

Autenticazione #

Tutti i servizi esposti sotto il path auth necessitano di autenticazione, fornita nell’header Authorization. Le Cloudlet Livebase supportano nativamente due sistemi di autenticazione: uno basato su JSON Web Token (da qui in poi abbreviato in JWT) o ed uno di tipo HTTP Basic, come spiegato in dettaglio qui.

JSON Web Token #

Se si utilizza il sistema basato su token JWT va specificato il seguente header:
Authorization: Bearer $TOKEN

Dove $TOKEN va sostituito con il token ottenuto in risposta dal servizio getJwtToken.

Basic Authentication #

Se si utilizza la Basic Authentication va specificato il seguente header:
Authorization: Basic $AUTH

Dove $AUTH va sostituito con la coppia di credenziali <username>:<password> codificata in Base64.

Gestione dei token JWT #

Le operazioni di gestione dei token JWT per l’autenticazione sulle API di una Cloudlet sono fornite dai seguenti endpoint:

  • public/token/getJwtToken
  • auth/token/refreshJwtToken

public/token/getJwtToken #

Offre funzionalità di generazione di un token JWT, utilizzabile nell’header Authorization di future richieste alle API della Cloudlet esposte sotto il path auth

Metodi supportati: POST.

POST #

Restituisce il token JWT generato per l’utente passato nel body, se le credenziali fornite sono corrette.

Comando cURL:

curl -X POST \
    -H "Content-Type: application/json" \
    -d ${BODY} \
    ${CLOUDLET}/public/token/getJwtToken?format=json

Dove ${BODY} è il corpo della richiesta e ${CLOUDLET} l’URL della Cloudlet che desideriamo interrogare.

Il corpo deve essere un JSON contenente i campi username e password, ovvero le credenziali dell’utente per cui vogliamo generare il token. Per esempio:

{
    "username":"asd",
    "password":"test"
}

auth/token/refreshJwtToken #

Offre funzionalità di rinnovamento di un token JWT, ottenendo in risposta un nuovo token JWT utilizzabile nell’header Authorization di future richieste alle API della Cloudlet esposte sotto il path auth

Metodi supportati: GET.

GET #

Restituisce il token JWT generato per l’utente relativo al token JWT specificato nell’header, se tale token è valido.

Comando cURL:

curl -s ${CLOUDLET}/auth/administration/members?format=json \
    -H "Authorization: Bearer $TOKEN" | jq

Dove ${TOKEN} è un token valido da rinnovare e ${CLOUDLET} l’URL della Cloudlet che desideriamo interrogare.

Gestione degli utenti #

Le operazioni di gestione degli utenti di una Cloudlet sono fornite dai seguenti endpoint:

  • auth/administration/member
  • auth/administration/members
  • auth/administration/members/{id}
  • auth/administration/members/{id}/resetPassword
  • public/administration/setPassword

auth/administration/member #

Offre funzionalità per la gestione dell’utente attuale, ovvero dell’utente che sottomette le richieste all’endpoint.

Metodi supportati: GET.

GET #

Restituisce le informazioni relative all’utente attuale.

Esempio di comando cURL:

curl -s ${CLOUDLET}/auth/administration/member?format=json \
    -H "Authorization: $AUTH_HEADER" | jq

Dove ${CLOUDLET} va sostituito con l’URL della Cloudlet che desideriamo interrogare, e $AUTH_HEADER con una delle opzioni disponibili illustrate nella sezione Autenticazione.

Un esempio di risultato in formato JSON è il seguente:

{
  "id": "1",
  "username": "john.doe",
  "email": "john.doe@mail.com",
  "notes": "Autogenerated admin account",
  "profile": "Member",
  "timeFormat": "HH:mm",
  "dateFormat": "dd/MM/yyyy",
  "timeZone": "Europe/London",
  "language": "en"
}

auth/administration/members #

Offre funzionalità per la gestione di insieme degli utenti della Cloudlet.

Metodi supportati: GET, POST.

GET #

Restituisce l’elenco di tutti gli utenti registrati nella Cloudlet.

Esempio di comando cURL:

curl -s ${CLOUDLET}/auth/administration/members?format=json \
    -H "Authorization: $AUTH_HEADER" | jq

Dove ${CLOUDLET} è l’URL della Cloudlet che desideriamo interrogare, e $AUTH_HEADER è una delle opzioni disponibili illustrate nella sezione Autenticazione.

Un esempio di risultato in formato JSON è il seguente:

[
    {
        "id": 1,
        "username": "asd",
        "url": "http://hs-on-port-12716.127-0-0-1.nip.io/asd/NewCloudlet1/auth/administration/members/1"
    },
    {
        "id": 103,
        "username": "asd2",
        "url": "http://hs-on-port-12716.127-0-0-1.nip.io/asd/NewCloudlet1/auth/administration/members/103"
    },
    {
        "id": 105,
        "username": "asd3",
        "url": "http://hs-on-port-12716.127-0-0-1.nip.io/asd/NewCloudlet1/auth/administration/members/105"
    }
]

POST #

Crea un nuovo utente per la Cloudlet.

Comando cURL:

curl -X POST \
    -H "Authorization: $AUTH_HEADER" \
    -H "Content-Type: application/json" \
    -d ${BODY} \
    ${CLOUDLET}/auth/administration/members?format=json

Dove $AUTH_HEADER è una delle opzioni disponibili illustrate nella sezione Autenticazione, ${BODY} il corpo della richiesta, e ${CLOUDLET} l’URL della Cloudlet che desideriamo interrogare.

Il corpo deve essere un JSON contenente almeno i campi username, email e profile, che corrispondono agli omonimi dell’oggetto User che stiamo creando. Per esempio:

{
    "username": "asd",
    "email":"john.doe@mail.com",
    "profile": "Member"
}

Il servizio ritorna l’__id del nuovo utente.

auth/administration/members/{id} #

Offre funzionalità per la gestione del singolo utente di una Cloudlet.

Metodi supportati: GET, PUT, DELETE.

GET #

Restituisce le informazioni relative all’utente con identificativo pari a {id}.

Comando cURL:

    curl -s \
        -H "Authorization: $AUTH_HEADER" \
        ${CLOUDLET}/auth/administration/members/{id}?format=json | jq

Dove $AUTH_HEADER è una delle opzioni disponibili illustrate nella sezione Autenticazione e ${CLOUDLET} l’URL della Cloudlet che desideriamo interrogare.

Un esempio di risultato in formato JSON è il seguente:

    {
        "id": "103",
        "username": "asd2",
        "email": "john.doe@mail.com",
        "profile": "Member"
    }

PUT #

Aggiorna le informazioni dell’utente con identificativo pari a {id}.

Comando cURL:

    curl -X PUT \
        -H "Authorization: $AUTH_HEADER" \
        -H "Content-Type: application/json" $(: override the Content-Type autodefined with -d flag)\
        -d ${BODY} \
        ${CLOUDLET}/auth/administration/members/{id}?format=json

Dove $AUTH_HEADER è una delle opzioni disponibili illustrate nella sezione Autenticazione, ${BODY} il corpo della richiesta, e ${CLOUDLET} l’URL della Cloudlet che desideriamo interrogare.

Possono essere restituiti due tipi di risposte:

  • Se l’aggiornamento va a buon fine, la risposta ha codice 200 e contiene la stringa Update Complete;
  • Se l’aggiornamento fallisce, la risposta ha un codice nel formato 4xx o 5xx e contiene una stringa che chiarisce il tipo di errore.

DELETE #

Elimina l’utente con identificativo pari a {id}.

Comando cURL:

    curl -X DELETE \
        -H "Authorization: $AUTH_HEADER" \
        -H "Content-Type: application/json" \
        ${CLOUDLET}/auth/administration/members/{id}?format=json

Dove $AUTH_HEADER è una delle opzioni disponibili illustrate nella sezione Autenticazione e ${CLOUDLET} l’URL della Cloudlet che desideriamo interrogare.

Possono essere restituiti due tipi di risposte:

  • Se l’eliminazione va a buon fine, la risposta ha codice 200 e contiene la stringa Delete completed;
  • Se l’eliminazione fallisce, la risposta ha codice 500 e contiene una stringa che chiarisce il tipo di errore.

auth/administration/members/{id}/resetPassword #

Offre funzionalità per la reimpostazione della password di un singolo utente della Cloudlet.

Metodi supportati: GET.

GET #

Avvia il processo di recupero della password per l’utente con identificativo pari a {id}.

Comando cURL:

    curl -s \
        -H "Authorization: $AUTH_HEADER" \
        ${CLOUDLET}/auth/administration/members/{id}/resetPassword?format=json | jq

Dove $AUTH_HEADER è luna delle opzioni disponibili illustrate nella sezione Autenticazione e ${CLOUDLET} l’URL della Cloudlet che desideriamo interrogare.

Il metodo può restituire due risposte:

  • Se la richiesta di reimpostazione password è accettata, la risposta ha codice 205;
  • Se la richiesta è respinta, ad esempio per autorizzazioni insufficienti, la risposta ha codice 401.

public/administration/setPassword #

Offre funzionalità per completare il processo di recupero password iniziato con la GET al precedente endpoint.

Metodi supportati: GET, POST.

GET #

Restituisce una pagina di cortesia per l’impostazione della password. È consigliabile inviare questa richiesta dalla barra indirizzi del proprio browser, con il seguente URL:

${CLOUDLET}/public/administration/setPassword?format=json

Con ${CLOUDLET} URL della Cloudlet che stiamo accedendo.

POST #

Effettua il reset della password. Questa richiesta viene eseguita in automatico alla sottomissione della pagina di cortesia, includendo nel corpo il token di autenticazione e il nuovo valore della password.

Possono essere restituite due risposte:

  • Se la richiesta di reimpostazione password è accettata, la risposta ha codice 205;
  • Se la richiesta è respinta, ad esempio per autorizzazioni insufficienti, la risposta ha codice 401.