skip to main content

REST services

A Cloudlet exposes REST services for managing its users.

Livebase Cloudlets expose a set of REST endpoints that allow you to manage their users with no access to a front-end. All endpoints accept OPTIONS requests in order to return information such as the set of HTTP methods actually supported or the allowed values ​​for the headers, and can be queried through various utilities such as cURL or Postman.

REST APIs accept requests and responses in XML and JSON formats, and you can choose between the two by defining the format parameter in the URL query string, with an xml or json value.

User management #

The operations for managing users of a Cloudlet are provided by the following endpoints:

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

auth/administration/member #

Provides functionality for managing the current user, i.e. the user submitting requests to the endpoint.

Supported methods: GET.

GET #

Returns information about the current user.

Example of cURL command:

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

Where ${CLOUDLET} has to be replaced with the URL of the Cloudlet we wish to query, and $AUTH with the pair of credentials <username>:<password> encoded in Base64.

An example of a JSON-formatted result is as follows:

{
  "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 #

Provides functionality for managing the users of a Cloudlet as a whole.

Supported methods: GET, POST

GET #

Returns a list of all users registered in the Cloudlet.

cURL command:

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

Where ${CLOUDLET} is the URL of the Cloudlet we wish to query, and $AUTH is the <username>:password> credentials pair as encoded in Base64.

An example of a JSON-formatted result is as follows:

[
    {
        "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 #

Creates a new user for the Cloudlet.

cURL command:

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

Where $AUTH is the <username>:password> credentials pair as encoded in Base64, ${BODY} the body of the request, and ${CLOUDLET} the URL of the Cloudlet we wish to query.

The request body must be a JSON containing at least the username, email and profile fields, which correspond to the homonymous fields of the User object we are creating. For instance:

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

The service returns the __id for the new user.

auth/administration/members/{id} #

Provides functionality for managing the single user of a Cloudlet.

Supported methods: GET, PUT, DELETE

GET #

Returns information about the user having {id} as its identifier.

cURL command:

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

Where $AUTH is the <username>:password> credentials pair as encoded in Base64, and ${CLOUDLET} the URL of the Cloudlet we wish to query.

An example of a JSON-formatted result is as follows:

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

PUT #

Updates the information about the user having {id} as its identifier.

cURL command:

    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

Where $AUTH is the <username>:password> credentials pair as encoded in Base64, ${BODY} the body of the request, and ${CLOUDLET} the URL of the Cloudlet we wish to query.

Two kinds of responses can be returned:

  • If the update is successful, the response has code 200 and contains the string Update Complete;
  • If the update fails, the response has a code in the format 4xx or 5xx and contains a string clarifying the type of error.

DELETE #

Deletes the user having {id} as its identifier.

cURL command:

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

Where $AUTH is the <username>:password> credentials pair as encoded in Base64, and ${CLOUDLET} the URL of the Cloudlet we wish to query.

Two kinds of responses can be returned:

  • If the deletion is successful, the response has code 200 and contains the string Delete completed;
  • If the deletion fails, the response has code 500 and contains a string clarifying the type of error.

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

Provides functionality for resetting the password of a single Cloudlet user.

Supported methods: GET.

GET #

Begins the password recovery process for the user having {id} as its identifier.

cURL command:

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

Where $AUTH is the <username>:password> credentials pair as encoded in Base64, and ${CLOUDLET} the URL of the Cloudlet we wish to query.

Two kinds of responses can be returned:

  • If the password reset request is accepted, the response has the code 205;
  • If the request is rejected, for example due to insufficient permissions, the response has a 401 code.

public/administration/setPassword #

Provides functionality to complete the password recovery process started with the GET request to the previous endpoint.

Supported methods: GET, POST.

GET #

Returns a courtesy page for setting the password. It is recommended to send this request from the address bar of your browser, with the following URL:

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

With ${CLOUDLET} being the URL of the Cloudlet we wish to query.

POST #

Executes the reset of your password. This request is performed automatically upon submission of the courtesy page, by including the authentication token and the new password value in its body.

Two kinds of responses can be returned:

  • If the password reset request is accepted, the response has the code 205;
  • If the request is rejected, for example due to insufficient permissions, the response has a 401 code.