API v3 overview
At this time, v3 includes only a subset of APIs.
We are publishing new endpoints every product release. If you are interested in using the new APIs, please contact our team!
Cloud4Wi REST APIs v3 provide you with more scalability and improved performances, and they introduce a new authentication method. Find more technical details below.
Retrieve API Key and Secret
On your Cloud4Wi Dashboard, go to Cloud4Wi APIs apps form the Settings > Marketplace page.
Create a new Service enabling the Read / Write scopes, according to your needs.
Finally, you can see the API Key and Secret clicking on the view icon.
Using your clientKey and clientSecret you can request for a token by calling the dedicated method (note: replace asterisks with your client key and secret)
If the client key and secret are correct, then the API will return a JWT token.
To access the resources, you have to put the token in the Authorization Header as Bearer (see the example below)
The JWT token expires after one day; to get a new one, restart and call again /v1/sts/login/services.
All endpoints will respond with an HTTP status code (find more details here):
- 200: Successful request
- 201: The request has been accepted
- 401: Unauthorised, invalid client key or secret
- 403: Forbidden, the service is not authorized to access the resource, or the token is invalid/expired
- 409: Conflict, the request had semantic errors or invalid parameters
- 404: The resource does not exist
- 410: This endpoint has been revoked or removed
- 429: Too many requests, rate limit exceeded
- 500: Uncaught application error
Error responses also include an error message where relevant.
Find below the example of an error message:
APIs Rate Limits
All versions of APIs are subject to limits:
- burst: 60 requests/minute
- daily: 15.000 requests/day
Where can I find the 'iss'?
The token used has the JWT format (https://en.wikipedia.org/wiki/JSON_Web_Token).
You can find the iss inside the payload of the JWT after you have decrypted it.
Example of decrypted JWT
How to check the rate limit?
In the API response, you can find some HTTP headers containing two types of limits.
Requests Rate Limits
Limits are on the number of requests to APIs.
X-Ratelimit-Limit-Minute: limit per minute
X-Ratelimit-Remaining-Minute: remaining requests per minute
X-Ratelimit-Limit-Day: limit per day
X-Ratelimit-Remaining-Day: remaining requests per day
Objects Rate Limits
Limits are on the number of objects elaborated (created/returned/edited/delete) through the APIs.
X-Ratelimit-Limit-<object>-Day: limit per object</object>
X-Ratelimit-Remaining-<object>-Day: remaining objects per day</object>
Where <object> is the object to which the limit refers</object>
If you reach any of the limits, then the API will return an HTTP/1.1 429 status code to the client with the following JSON body:
What is the 'cid'?
The 'cid' a string that univocally identifies an object.
It is related to the type of the object of the request, for example in the API
the 'cid' is the identifier of the customer.
Where can I find the 'cid' of the organization?
You can find your organization 'cid' in the Admin Panel in the section /services
How to use the 'sid' in the search APIs?
You can use the 'sid' (scroll id) to retrieve a large number of results from a search request.
You have to execute an initial search request without the 'sid' to initialize the scroll session. The API will return the 'sid' parameter in the response.
As a second step, you have to set the received 'sid' along with the following requests. This response will generate a new 'sid', that you can use to retrieve the next batch of results, and so on.
You can repeat this process in a loop until the API will not return any result.
The time interval between 2 requests is 60 seconds; after that interval, the 'sid' expires, and the API will not return any result until you submit a new 'sid'.