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

{ "DeviceId": "1234-234234-abcdef-134adf", "DeviceKey": "AsdfsdjI23421.sdfasdf...." }

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"}'

All input values should be in string format.

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",
        }
]

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