# OTA Update APIs

Deploy software updates or container updates on your remote IoT devices via the OTA update REST API.

Note:

OTA updates are deployed in the order in which they are submitted. For example, if a device was down for some reason when the OTA update job was submitted and later when it comes back up, OTA deployments waiting to be executed on the device will be executed one by one in the order in which they were submitted.

Before submitting a deployment or job, you need to define a workflow first. Use the workflow to submit a deployment/job on a specific device (DeviceId) or on a group of devices (DeviceGroup) or on a tag (Device Tags).

The idea behind separating workflow and deployment is reusability and repeatability.

# 1. Define a Workflow

curl https://api.socketxp.com/v1/workflow \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" \
  -d '{“Name”: "print-date-workflow”, “Command": "date"}'

A workflow could be a simple linux command or a shell script or a python program that needs to be run.

Name: Summarizes the nature of the workflow to be executed.
Command: The command that needs to be run on the device.

Sample inputs for the Command field are:

“ls -l | grep myfile”
“date”
“sh /home/john/script.sh”
“python /home/john/check_temperature.py”
"reboot"
"service sshd restart"

Wherever possible provide full path names for files.

# Sample Response:

{"WorkflowId": "678edc16-96d1-4ea2-a99c-0474c2449381"}

Use the above WorkflowId to submit a job on a particular device or a group of devices.

# 2. Get a Workflow

Retrieve details about a workflow using the following API.

curl https://api.socketxp.com/v1/workflow/:workflow_id \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Sample Response

{
    "WorkflowId": "678edc16-96d1-4ea2-a99c-0474c2449381",
    "Name": "print-date-workflow",
    "Command": "date",
    "CreatedTime": "2002-01-19 10:05:22"
}

Retrieve all workflows of a user using the following API.

curl https://api.socketxp.com/v1/workflow \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# 3. Delete a Workflow

To delete a workflow, use the following API.

curl https://api.socketxp.com/v1/workflow/:workflow_id \
  -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Sample Response

200 OK

# Deployment

# 1. Submit a Deployment

Submit a deployment/job on a device using the DeviceId option.

curl https://api.socketxp.com/v1/job \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" \
  -d '{“Name”: “test-job-123”, “DeviceId”: "sensor-dev12345”, "WorkflowId": "678edc16-96d1-4ea2-a99c-0474c2449381" }'

Submit a deployment/job on a group of devices using the DeviceGroup option.

curl https://api.socketxp.com/v1/job \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" \
  -d '{“Name”: “test-job-123”, “DeviceGroup”: "temp-sensor”, "WorkflowId": "678edc16-96d1-4ea2-a99c-0474c2449381" }'

Submit a deployment/job on group of devices with a given tag using the TagId option.

curl https://api.socketxp.com/v1/job \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" \
  -d '{“Name”: “test-job-123”, “TagId”: "temp-sensor”, "WorkflowId": "678edc16-96d1-4ea2-a99c-0474c2449381" }'

# Description:

Submit a deployment/job for execution.

# Sample Response:

{"JobId": "4cad67dd-ab67-42ee-a293-4db493cab9ea"}

Use the above JobId to query the status and result of the job.

# 2. Get a Deployment with Result

curl https://api.socketxp.com/v1/job/:job_id \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Description:

Get the results of a submitted job using its JobId.

# Sample Usage

curl https://api.socketxp.com/v1/job/4cad67dd-ab67-42ee-a293-4db493cab9ea \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Sample Response:

{
	“JobId”: “4cad67dd-ab67-42ee-a293-4db493cab9ea”,
	“JobName”: “test-job-123,
	“DeviceId”: “sensor-dev12345”,
	“Command”: “date”,
	“StartTime”: “Feb 8, 2002, 15:04:13 PST”,
	“EndTime”: “Feb 8, 2002, 15:04:14 PST”,
	“Result”: “Fri Feb 8 15:04:14 UTC 2002}

# 3. Get All Deployments with Results

curl https://api.socketxp.com/v1/job \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Description:

Get the results of all submitted jobs of a user.

# Sample Usage

curl https://api.socketxp.com/v1/job \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Sample Response

200 OK

[{
	“JobId”: “4cad67dd-ab67-42ee-a293-4db493cab9ea”,
	“JobName”: “test-job-123,
	“DeviceId”: “sensor-dev12345”,
	“Command”: “date”,
	“StartTime”: “Feb 8, 2002, 15:04:13 PST”,
	“EndTime”: “Feb 8, 2002, 15:04:14 PST”,
	“Result”: “Fri Feb 8 15:04:14 UTC 2002}, 
{
	“JobId”: “5cad67eb-dk67-42ee-a293-4db493cab7wk”,
	“JobName”: “test-job-123,
	“DeviceId”: “sensor-dev12345”,
	“Command”: “whoami”,
	“StartTime”: “Feb 8, 2002, 15:07:13 PST”,
	“EndTime”: “Feb 8, 2002, 15:07:14 PST”,
	“Result”: “john”
}]

# 4. Delete a deployment

curl https://api.socketxp.com/v1/job/:job_id \
  -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Description:

Delete a job. It is a good practise to delete all your executed jobs and keep your job queue short.

# Sample Usage:

curl https://api.socketxp.com/v1/job/4cad67dd-ab67-42ee-a293-4db493cab9ea \
  -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" 

# Sample Response:

200 OK