Servizi REST

Le Cloudlet Livebase espongono una serie di endpoint REST che consentono di gestirne gli utenti 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.

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: Basic $AUTH" | jq

Dove ${CLOUDLET} va sostituito con l’URL della Cloudlet che desideriamo interrogare, e $AUTH con la coppia di credenziali <username>:<password> codificata in Base64.

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: Basic $AUTH" | jq

Dove ${CLOUDLET} è l’URL della Cloudlet che desideriamo interrogare, e $AUTH è la coppia <username>:<password> codificata in Base64.

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: Basic $AUTH" \
    -H "Content-Type: application/json" \
    -d ${BODY} \
    ${CLOUDLET}/auth/administration/members?format=json

Dove $AUTH è la coppia <username>:<password> codificata in Base64, ${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: Basic $AUTH" \
        ${CLOUDLET}/auth/administration/members/{id}?format=json | jq

Dove $AUTH è la coppia <username>:<password> codificata in Base64, 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: Basic $AUTH" \
        -H "Content-Type: application/json" $(: override the Content-Type autodefined with -d flag)\
        -d ${BODY} \
        ${CLOUDLET}/auth/administration/members/{id}?format=json

Dove $AUTH è la coppia <username>:<password> codificata in Base64, ${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: Basic $AUTH" \
        -H "Content-Type: application/json" \
        ${CLOUDLET}/auth/administration/members/{id}?format=json

Dove $AUTH è la coppia <username>:<password> codificata in Base64, 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: Basic $AUTH" \
        ${CLOUDLET}/auth/administration/members/{id}/resetPassword?format=json | jq

Dove $AUTH è la coppia <username>:<password> codificata in Base64 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.