Device APIs
1. Create a device
Use the following API to create a device and get back the DeviceID and DeviceKey details for the device. This API is useful if you want to automate device setup and configuration.
This API is useful if you want to pre-populate the /var/lib/socketxp/device.key file in the IoT device without executing the socketxp login <authtoken> command in the device.
curl https://api.socketxp.com/v1/devices \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-auth-token-goes-here>" \
-d '{"DeviceName": "my-device-name", "DeviceGroup": "sensor"}'
Sample Response:
200 OK
2. Update a device
2a. Update a device's information
Use the following API to update device information such as: device name, device group, customer name and customer site.
curl https://api.socketxp.com/v1/devices/:device_id \
-X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-auth-token-goes-here>" \
-d '{"DeviceName": "my-device-name", "DeviceGroup": "my-device-group", "CustomerName":"my-customer-name", "CustomerSite":"Folsom Street, San Francisco"}'
Sample Usage:
curl https://api.socketxp.com/v1/devices/1abc-abcde-acbdefgh-a1b3c3d4-abc \
-X PATCH \
-H "Authorization: Bearer <your-auth-token-goes-here>" \
-d '{"DeviceName": "sensor-12345", "DeviceGroup": "light-sensor", "CustomerName":"John Inc.", "CustomerSite":"San Francisco"}'
Sample Response:
200 OK
2b. Update a device's geographic (GPS) location.
curl https://api.socketxp.com/v1/devices/location/:device_id \
-X POST \
-H "Authorization: Bearer <your-auth-token-goes-here>" \
-d '{"Lat": 37.813699649742475, "Lng": -122.47787639433689}'
Description:
If your device has a GPS integrated with it or if you could fetch the device's GPS co-ordinates(Longitude and Latitude) from your 4G/5G network provider or using Google's GeoLocation API, you can update the GPS co-ordinates of your device with SocketXP using the following API.
This API is useful if you want to view your device's geo location in the SocketXP portal's map view.
Note: The Latitude and Longitude values are float values and not string.
Sample Usage:
curl https://api.socketxp.com/v1/devices/location/1abc-abcde-acbdefgh-a1b3c3d4-abc \
-X POST \
-H "Authorization: Bearer <your-auth-token-goes-here>" \
-d '{"Lat": 37.813699649742475, "Lng": -122.47787639433689}'
Sample Response:
200 OK
3. Get devices
3a. GET all devices (one page at a time)
curl https://api.socketxp.com/v1/devices/:page_num/:rows_per_page \
-X GET \
-H "Authorization: Bearer <your-auth-token-goes-here>"
Description:
The API returns the devices list one page at a time. Say for example, if there are totally 100 devices, users can display them as 4 different pages (page_num) with each page displaying 25 devices (rows_per_page).
Sample Usage:
curl https://api.socketxp.com/v1/devices/1/5 \
-X GET \
-H "Authorization: Bearer <your-auth-token-goes-here>"
Sample Response:
200 OK
{
“Devices” : [
{
"DeviceId": "0000234234",
"DeviceName": "temp-sensor-floor1",
"DeviceGroup": "temp-sensor",
"LocalAddr": "127.0.0.1",
"LocalPort": "22",
"DeviceStatus": "Online",
},
{
"DeviceId": "0000234235",
"DeviceName": "temp-sensor-floor2",
"DeviceGroup": "temp-sensor",
"LocalAddr": "127.0.0.1",
"LocalPort": "22",
"DeviceStatus": "Online",
},
{
"DeviceId": "0000234236",
"DeviceName": "temp-sensor-floor3",
"DeviceGroup": "temp-sensor",
"LocalAddr": "127.0.0.1",
"LocalPort": "22",
"DeviceStatus": "Online",
},
{
"DeviceId": "0000234237",
"DeviceName": "temp-sensor-floor4",
"DeviceGroup": "temp-sensor",
"LocalAddr": "127.0.0.1",
"LocalPort": "22",
"DeviceStatus": "Online",
},
{
"DeviceId": "0000234238",
"DeviceName": "temp-sensor-floor5",
"DeviceGroup": "temp-sensor",
"LocalAddr": "127.0.0.1",
"LocalPort": "22",
"DeviceStatus": "Offline",
}
],
"TotalNumDevices": 20
}
3b. Get select devices
curl https://api.socketxp.com/v1/devices \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-auth-token-goes-here>" \
-d '[{"DeviceId":"dev0000000123"},{"DeviceId":"dev0000000124"}]'
Sample Response:
200 OK
[
{
"DeviceId": "dev0000000123",
"DeviceName": "CO-sensor-floor1",
"DeviceGroup": "CO-sensor",
"LocalAddr": "127.0.0.1",
"LocalPort": "22",
"DeviceStatus": "Online",
},
{
"DeviceId": "dev0000000124",
"DeviceName": "CO-sensor-floor2",
"DeviceGroup": "CO-sensor",
"LocalAddr": "127.0.0.1",
"LocalPort": "22",
"DeviceStatus": "Online",
}
]
3c. Get devices matching filters
Use the following GET API to retrieve devices matching specific filters such as the device name, device group, device ID, device status, device tag etc.
curl https://api.socketxp.com/v1/devices/:page_num/:rows_per_page/filters?device_name=value&device_group=value&device_id=value&device_status=value&device_tag=value\
-X GET \
-H "Authorization: Bearer <your-auth-token-goes-here>"
Description:
Filter rules are set as query parameters in the URL string. Only devices that match all the given conditions (conditions are AND'ed and not OR'ed) will be returned in the query response.
The API returns the device list as one page at a time. For example, if there are totally 100 devices, users can display them as 4 different pages (page_num) with each page displaying 25 devices(rows_per_page).
Sample Usage:
curl https://api.socketxp.com/v1/devices/1/25/filters?device_name="test-sensor-12345"&device_group="CO-sensor"&device_id="abc-1234-abcdef-5678-a1b2c3d4-abc"&device_status="offline"\
-X GET \
-H "Authorization: Bearer <your-auth-token-goes-here>"
Sample Response:
200 OK
[
{
"DeviceId": "abc-1234-abcdef-5678-a1b2c3d4-abc",
"DeviceName": "test-sensor-12345",
"DeviceGroup": "CO-sensor",
"LocalAddr": "127.0.0.1",
"LocalPort": "22",
"DeviceStatus": "Offline",
}
]
3d. GET device's geographic (GPS) location:
curl https://api.socketxp.com/v1/devices/location \
-X GET \
-H "Authorization: Bearer <your-auth-token-goes-here>"
Description:
The API returns a list of all devices with its GPS co-ordinates currently saved in the database.
Sample Usage:
curl https://api.socketxp.com/v1/devices/location \
-X GET \
-H "Authorization: Bearer <your-auth-token-goes-here>"
Sample Response:
[
{"DeviceId":"abc-1234-abcdef-5678-a1b2c3d4-abc","Lat":0,"Lng":0},
{"DeviceId":"efg-1234-abcdef-5678-a1b2c3d4-efg","Lat":-26.034009300296415,"Lng":27.954121158800206}
]
4. Delete a device
curl https://api.socketxp.com/v1/devices/:device_id \
-X DELETE \
-H "Authorization: Bearer <your-auth-token-goes-here>"
Sample Usage:
curl https://api.socketxp.com/v1/devices/dev0000000124 \
-X DELETE \
-H "Authorization: Bearer <your-auth-token-goes-here>"
Sample Response:
200 OK