The IoT REST APIs enable you to report instrumentation data directly to the EUM Server. You can use any platform or language that has support for HTTPS requests and JSON.
This page describes how to create a JSON request body, form the resource URI, and make an HTTPS request to the IoT REST APIs to report instrumentation data for the three supported events.
Follow the steps below to get your EUM App Key and use the IoT REST API:
Check the Requirements
Before you get started, make sure you meet the following requirements:
- Get an EUM App Key
- Platform/language that supports HTTPS requests.
- JSON support
Form the IoT REST URLs
To form the IoT Monitoring REST resource URL, you will need to know the IoT REST API base URL and port as well as your App Key.
IoT REST API Base URL
The IoT REST API base URL depends on your Controller location. See the IoT REST API row on SaaS Domains and IP Ranges. For example, the IoT base URL for the Americas region would be:
After creating your IoT Application, use your App Key to test your IoT endpoint and look for a HTTP 200 response. For example, for the Americas region, run the following command:
With your App Key, you can form the IoT resource endpoints. See the Summary of the IoT endpoints for the list of supported resource endpoints and their descriptions.
Create the JSON Request Body
You report device information and events in a JSON request body. The JSON includes an array of beacon objects, with each beacon object containing device data and events. The array enables you to transmit data from multiple devices in one request to the EUM Server. You can transmit up to 200 beacons per request.
Save the JSON below to a file (e.g., t
estBeacon.json) and replace the values for the timestamp properties with integers representing the UNIX Epoch time in milliseconds. The JSON contains the three supported events
errorEvents for a smart thermostat. In the next two steps, you will validate and send the JSON as a beacon to the IoT REST API.
Transmit the Beacon Data
To send the beacon, you post the JSON request body to the
/beacons endpoint. Again, in this cURL example, use the JSON you saved to the file
testBeacon.json and replace <appKey> with your EUM App Key:
If the beacons were transmitted successfully, the IoT REST API will return the HTTP Status Code 202:
Verify the Instrumentation in the Controller UI
See Confirm the IoT Application Reported Data to the Controller to verify the instrumentation.
Correlate Business Transactions with Network Requests (Optional)
To correlate business transactions (BTs) with network requests, you need to have instrumented a business application and enabled business transactions in the Controller UI. See Correlate Business Transactions for IoT Monitoring to learn more.
The steps below show you how to get the BT response headers and use them to correlate the BT with an IoT Network Request event.
Make a network request that includes the AppDynamics HTTP request headers
ADRUMand ADRUM_1 to one of your business applications:
The business application will return response headers that contain information for correlating business transactions. If you were to print these BT response headers, you would see something like the following:
Create a beacon file
btCorrelation.jsonwith the returned BT response headers (only those headers that include
ADRUM_*).You assign the returned
ADRUM_*response headers from the network event request to the business application to the object
responseHeadersin the beacon as shown below.
Send the beacon containing the BT headers to the EUM Server with a cURL command similar to the one here:
For a successful call, the response headers should be similar to the following:
In the Controller UI, you should be able to view the correlated business transaction in the Device Details dialog.
Customize the IoT REST API Instrumentation (Optional)
You can further customize the IoT instrumentation using the IoT REST API. See the latest IoT REST API documentation or the previous versions listed below:
Run the Sample Python Application
The sample Python application uses the IoT REST API to send sample data for Custom, Network Request, and Error events. The Network Request events include correlated business transactions. The data mocks a smart car application, capturing usage information, network performance, and errors.
To run the sample app, follow the instructions given in the GitHub repository iot-rest-api-sample-apps.
Troubleshoot the IoT REST API Instrumentation
The sections below provide instructions for troubleshooting your IoT REST API Instrumentation.
Verify Your IoT App Has Been Enabled
Using your App Key, verify that your IoT app has been enabled:
If your App Key has been enabled, you should get the following response:
If the App Key does not exist:
You can use the validate beacon endpoint (
/validate-beacons) to verify that the beacon's JSON request body complies with the REST API schema.
You are not required or recommended to validate beacons before transmitting them. You should only use this endpoint in development for testing and troubleshooting.
In this cURL example, you are verifying that the JSON given in the file
testBeacon.json is valid. Replace
<appKey> with your EUM App Key.
If the JSON request body containing the beacon data is valid, the IoT Monitoring REST API will return the HTTP Status 200:
If the JSON request body is invalid, the IoT REST API will return the HTTP Status 422 and a response body with the description of the error message.