Cloudesire REST API Introduction #

The Cloudesire platform exposes REST API and uses JSON as data exchange format.

URI format #

To interact with API resources, you need to use an URL with the format:

https://{domain}/api/{resource}/{resourceId}

Domains #

Every marketplace has a different API domain, depending on its environment:

• demo-eng.cloudesire.com: backend-demo-eng.cloudesire.com

As example, the full URL endpoint of demo-eng.cloudesire.com would be:

https://backend-demo-eng.cloudesire.com/api/

Versioning #

Client should set the request parameter apiVersion globally on every request to avoid failures while the API evolves. This value is a string representation in yyyymmdd format of the date when a breaking changes is introduced to support new features.

GET /api/productVersion?apiVersion=20180312 HTTP/1.1

To discover the latest available version check the source of ApiVersion.java.

Authentication #

The API support two different authentication methods:

• Via username/email and password supplied as standard Basic Authentication;
• Via an authentication token, short-lived or permanent, that can also be requested via API.

Permanent authentication token #

You can request a permanent login token in the profile section once logged into the marketplace control panel, and this should be the preferred authentication method when developing an integration with the Cloudesire API.

Once obtained the token, set on every HTTP request two additional headers:

• CMW-Auth-Token: the token you got from your profile

A good test would be to retrieve your user profile:

GET /api/user/me HTTP/1.1
CMW-Auth-Token: my_token


HTTP/1.1 200 OK
Content-Type: application/json
Date: Tue, 13 Jan 2015 15:05:52 GMT

{
    "acceptedTerms": true,
    "activated": true,
    "activationDate": "2014-01-01T00:00:00Z",
    "address": {
    "address": "Via Pisana",
    "city": "Pisa",
    "country": "ITALY",
    "countryCode": "IT",
    "id": 4,
    "zipCode": "12345"
    },
    "company": {
        "url": "company/1"
        },
    "creationDate": "2014-07-02T08:20:01Z",
    "email": "dev@cloudesire.com",
    "enabled": true,
    "environment": "cloudesire",
    "id": 3,
    "name": "Demo Vendor",
    "newbie": false,
    "phoneNumber": "0123456789",
    "self": "user/3",
    "userName": "vendor",
    "userRole": "ROLE_VENDOR"
}

A 200 response with a json body representing your user profile means that you successfully authenticated and you can start developing the integration.

Response codes #

Error response #

Every time a non-successful response in generated, a JSON payload returns with a list of error messages in errorHolders field, with a human-readable message in the error field plus an error message in key field with %placeholder% that can be replaced in extraFields field:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "errorHolders": [{
    "key": "unsupported-file-type-%detected%-%supported%",
    "error": "Unsupported file type: image/jpeg",
    "extraFields": {
        "detected": "image/jpeg",
        "supported": "image/png"
    }
  }]
}

Common Characteristics #

There a few common traits that needs to be know:

• there is always a self field that represent its unique URL (e.g.: user/3), use GET on it to fetch the resource;
• referenced resources (e.g.: user.company), are referenced by an object containing an url field with the resource endpoint (e.g.: company/123)
• Date field are in ISO 8601 format containing both time and timezone information (UTC as default).

HTTP Methods #

Usually each resource support the basic CRUD operations mapped on five HTTP verbs:

• GET for retrieving
• POST for creation
• PUT for modification
• DELETE for deletion
• PATCH for partial updates

Sometimes the method PATCH is used either for partial modification or for custom actions.

API Reference #

Look at the dedicated API Reference page.