Using the API#
Tools to test our API#
After obtaining your access token, you can use any available method to send HTTP requests to the Coiote IoT DM API. The following are a few tools that you may find useful.
You can learn how to get your access token in the Authentication section.
cURL is a command-line tool used for making requests to various servers and retrieving data. It is widely used for making HTTP requests. To test Coiote IoT DM API using cURL:
Open a terminal or command prompt.
Type "curl" followed by the URL with the endpoint you want to request and the desired options. You have to include the access token in the authorization header. For example:Replace
curl -i -X GET "http://#HOSTNAME/api/coiotedm/v3/devices" -H "accept: application/json" -H "authorization: Bearer #TOKEN"
#TOKENwith your actual access token and
#HOSTNAMEwith your actual hostname.
Execute the command by pressing Enter. cURL will send the request to the server and display the response on the terminal.
Postman is a popular API development and testing tool with a user-friendly interface for making HTTP requests. To test Coiote IoT DM API using Postman:
- Open Postman in the browser or download the Postman desktop app.
- Navigate to the new request tab.
Enter the URL in the address bar:Replace
#HOSTNAMEwith your actual hostname.
Include the API endpoint to which you want to send a request, for example:Replace
#HOSTNAMEwith your actual hostname.
Go to the Authorization tab. From the Type dropdown list select Bearer Token. Paste your access token.
- Customize your request by adding headers, query parameters, or request body content. You can do this by clicking on the corresponding tabs.
- Click Send. Postman will display the response received from the server, including the status code, headers, and response body.
- You can analyze the response data, save it, or perform additional actions. Postman provides features like response validation, saving requests in collections, or organizing requests into folders.
Swagger can be used only if the user's password is stored in the Coiote IoT DM DM IAM. It doesn’t work for Single sign-on users.
Swagger UI is a tool for visualizing and interacting with APIs that are documented using the OpenAPI Specification. Using Swagger you can expand API endpoints, view request/response details, try out requests directly from the UI, and see the corresponding responses.
To access Coiote IoT DM API in Swagger UI:
- Log in to your Coiote IoT DM account.
- Click the question mark icon in the top navigation bar.
- Go to Specification > API v3.
In the Swagger UI:
- Click Authorize and type your username and password. You will be granted an access token to make requests. Your token expires after around 5 minutes. After that time you have to authorize again.
- Select an endpoint and click Try it out.
- Type your search criteria and click Execute.
- Swagger UI displays your request in cURL and URL format along with the response and description of possible response codes.
Making a request#
Once you decide on a tool, you can start to form a request.
Identify the endpoint you want to use.
Decide which endpoint and method will provide you with the results you need. For example, to get a list of devices, you would use GET and the endpoint /devices. For a detailed description of available endpoints consult the API reference.
Use parameters to adjust your request.
Look for available query parameters to refine your request. If you want to get a list of devices that connected to the system in a selected period of time, you can use the parameter "lastSessionTime".
Evaluate the response.
The API response typically includes a status code, headers, and a response body. If your request from the example is successful, you will receive the status code 200. The headers will include information such as content-length, content-type and time of request. The response body will contain an array of device identifiers:
[ "device_id", "device_id", "device_id", "device_id", "device_id", "device_id", "device_id", "device_id" ]
You can encounter the following success response codes:
|200||Success||The request was successfully processed and the server sends back the requested content in the response body.|
|201||Created||The request to create a new resource was successful. The server includes information about the newly created resource in the response body or through headers.|
|204||No Content||The request was successfully processed, but there is no new data to include in the response body. This status code is often used for requests that update or delete a resource.|
Coiote IoT DM API implements the Standard HTTP error codes as well as custom codes. Every response body contains additional information about the error in JSON format.
Standard HTTP error codes
The following table lists possible error codes with a short explanation.
|400||bad request||The server can't process the request because of missing or malformed parameters, or invalid data. You should review the request details, make sure that all required parameters are provided correctly, and validate the syntax of any included data.|
|403||request forbidden||The server can't fulfill the request because you don’t have sufficient permissions for accessing the resource. Check your permissions and contact the server admin if you need help.|
|404||entity not found||The server couldn't locate the requested resource. This could happen, for example, because of a mistyped URL, a deleted or moved resource, or an invalid link or reference. You should verify that the requested URL is correct or check server-side configurations and file availability.|
|409||conflict with server state||The server can’t fulfill the request because of a conflict with the current state of the target resource. This error often happens when a requested resource has been modified by another user, blocking an update or modification request. You should revise your request or coordinate with other users to make sure that conflicting modifications are avoided.|
|429||too many requests||You have sent too many requests to the server within a given timeframe, exceeding the server's rate limit. You should implement mechanisms to control your request rate and respect the server's rate limiting policies.|
|503||service unavailable||The server is currently unable to process the request. This can happen when the server is experiencing high traffic, undergoing maintenance, or facing temporary resource limitations. You should wait for the server to become available again or contact the server administrator for more information on the expected downtime.|
Custom error codes
Custom error codes are implemented to provide more detailed and contextual explanations of the errors. The description for the error code depends on the endpoint and can be found in the request body. The following table lists a few examples of custom error codes with their possible descriptions.
|4000||The provided time range was invalid. The start date must be earlier than the end date and they must be past dates. / Payload is invalid.|
|4001||The provided limit was invalid. It must be an integer between 1 and 2048.|
|4002||The handler id must be a 24-byte hexadecimal string representation.|
|4003||The provided LwM2M URL was invalid. The correct format is '/x/y/z' with the values being numeric. / Kafka domain property is not configured for this domain.|
|4004||The available handlers limit is already reached.|
|4005||Provided handler URI is invalid or forbidden.|
|4006||Provided bootstrap server(s) is invalid or forbidden.|
|4030||The user does not have the permissions to perform monitoring actions.|
|4040||The device with the provided ID was not found. / The handler with the given id was not found.|
|4041||LwM2M resource with provided URL was not found. / The domain with the given id was not found.|
|4042||LwM2M resource is outside of the monitored range. Objects with ID between 1 and 65534 inclusive are monitored.|
|5030||System encountered error while processing request, please try again later.|
|5031||Monitoring is not enabled.|