# 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

# 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 (opens new window), 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",
        }
]

# 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