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 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.