1 Postman collection
2 Access
3 Authentication
- 3.1 OAuth
- 3.2 Token
4 Usage
- 4.1 GET
- 4.2 POST
- 4.3 PUT
- 4.4 PATCH
- 4.5 DELETE
5 Error reporting
- 5.1 Non_field_errors
- 5.2 Element specific errors
6 Rate Limit

Postman collection

This postman collection can be imported. On the collection level, the given settings can be modified.

Access

In order to use the API portal you must get a personal account from CloudSuite. We will give you a username and password. For the portal an IP accesslist is also needed.

Authentication

OAuth

This method is the authentication after 1 february 2024

To use the API you must use the created token by the OAuth service. A username and password will be given to fetch the token from the provided URL.

Field	Value

Field	Value
Grant type	Client Credentials
Access Token URL	https://id.cloudsuite.io/realms/CloudSuite/protocol/openid-connect/token
Access Token URL TEST	https://id.cloudsuite.io/realms/CloudSuite-test/protocol/openid-connect/token
Client ID	Supplied username
Client Secret	Supplied password
Scope	openid
Client Authentication	Send client credentials in body
Refesh token	same as access token url

The received token must be used in the header of each request to the API:

Key: Authorization
Value: Bearer 186262d49fd0855555a88bf9871e0cb592f456748

The token will expire. After the expiration the token must be renewed.

The URL will be https://api.cloudsuite.io/ (LIVE) and https://test-api.cloudsuite.io/ (TEST)

Token

The token authentication is deprecated as of 1 february 2024

To use the API you must use a supplied token and you will have access with your IP address.

The IP address must be given access (except for OAuth)

The received token must be used in the header of each request to the API:

Key: Authorization
Value: Token 186262d49fd0855555a88bf9871e0cb592f456748

A username and password is not required when using the token in the header

Usage

There is no fail-safe for this mechanism, so use it with caution

GET

Each call on the API can be done with a GET. This will return the requested object in json.

POST

Each object can be posted to the webservice. However, if the object already exists, an error will be given. This can only be used to do a one-time add to the database

PUT

Each object can be PUT into the database. An ID of the object is always required to use this. If a PUT is done, the entire object is replaced with the new data. The data of the entire object is required when doing a PUT.
If an object does not exist it will be added to the database.

PATCH

Most objects can be patched. This method allows a user to update a small item of the object. Only the changed data has to be given.

DELETE

Some objects can also be deleted from the database.

Error reporting

When an error occurs during a call it will look the same as an outgoing API body, except for two differences:

The error handling lies on the side of the integration, CloudSuite will not monitor, handle or report errors in another way then directly when giving the response.

Non_field_errors

An additional field can be added within each element. This element will describe the error regarding errors which are not related to specific elements.
This element is called: non_field_errors

Example request

{
  "key" : "Pricelist1",
  ...
  "product_contracts" : [
    {
      "key" : "Pricelist1_contract",
      "origin" : "CUSTOMER",
      "active" : true,
      ...
      ]
    }
  ]
}

Example error response

In this case the pricelist already exists when posting it.

{
    "non_field_errors": [
        "The fields origin, import_key must make a unique set."
    ]
}

Element specific errors

Also error reporting can be done on a specific element. In this case the same key is used exept that the response is a collection of strings.

Example request

The type of active is a boolean in the original request.

{
  "key" : "Pricelist1",
  "active" : "GG",
   ...
  "product_contracts" : [
   ...
      ]
    }
  ]
}

Example error response

{
    "active": [
        "\"GG\" is not a valid boolean."
    ]
}

Rate Limit

The test environment API has a rate limit of 5 calls per second per IP address. More calls can return a HTTP 429 - Too many requests error response.

The production environment has no rate limit, but use the number of parallel calls with caution

Documentation:

To use our documentation you must create a session with the given credentials:

Go to https://test.cloudsuite.io/admin and login with your credentials
When succesfully logged in the following URL's can be used to use the documentation.
https://test.cloudsuite.io/api/docs/
https://test.cloudsuite.io/api/swagger/

Cloudsuite REST API Documentation

Usage Info