How to Operate Devices

Requirements

A Valid API Key:Provisioned and provided by your platform administrator for South API.

Method

POST

Platform API Endpoint

/south/v80/devices/{device.id}/operation/response

Device API Endpoint

/south/v80/devices/{device.id}/operation/request

Two alternatives can be used to implement the Device side operations:

Synchronous The simplest way is using the Synchronous flow strategy that requires implementing a webservice in the device that can receive HTTP POST to the above defined URI and embedded the response JSON in to the HTTP response body

opengate api south operation workflows synchronous

Asynchronous Using the Synchronous flow strategy requires:
- Implementing a webservice in the device that can receive HTTP POST to the above defined URI
- Sending from the device a HTTP POST request to the above defined paltform URI

in both cases including a correctly formatted JSON documents in the POST body to set operation configurable parameters.

opengate api south operation workflows asynchronous simple

Find all options in the South API Operations section

Find the Platform side in How to remote operate devices through North API

Example 1. Synchronous Strategy example

1.1 Platform sends to the Device the Request

curl --request POST \
     --data-binary @opengate-api-south-operation-request.json \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_device_address]/south/v80/devices/{device.id}/operation/request \
     -H "Content-type: application/json"

1.2 Request. Platform originated Json Object

{
    "operation": {
        "request": {
            "timestamp": 1432454277950,
            "name": "REBOOT_EQUIPMENT",
            "parameters": {
                "type": "HARDWARE"
            },
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327"
        }
    }
}

2.1 Device answer in HTTP Response

HTTP/1.1 201 Created

2.2 Response. Device originated Json Object

{
    "version": "7.0",
    "operation": {
        "response": {
            "timestamp": 1432454278000,
            "name": 'REBOOT_EQUIPMENT',
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327",
            "resultCode": "SUCCESSFUL",
            "resultDescription": "No Error.",
            "variableList": [],
            "steps": []
        }
    }
}

Example 2. Asynchronous Strategy example

1.1 Platform sends to the Device the Request

curl --request POST \
     --data-binary @opengate-api-south-operation-request.json \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_device_address]/south/v80/devices/{device.id}/operation/request \
     -H "Content-type: application/json"

1.2 Request. Platform originated Json Object

{
    "operation": {
        "request": {
            "timestamp": 1432454277950,
            "name": "REBOOT_EQUIPMENT",
            "parameters": {
                "type": "HARDWARE"
            },
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327"
        }
    }
}

2.1 Device answer in HTTP Response

HTTP/1.1 201 Created

3.1 Device sends to the Platform a new HTTP Request with the response to the operation

curl --request POST \
     --data-binary @operation_response.json \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_opengate_address]/south/v80/devices/{device.id}/operation/response \
     -H "Content-type: application/json"

3.2 Device originated Response Json Object

{
    "version": "7.0",
    "operation": {
        "response": {
            "timestamp": 1432454278000,
            "name": 'REBOOT_EQUIPMENT',
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327",
            "resultCode": "SUCCESSFUL",
            "resultDescription": "No Error.",
            "variableList": [],
            "steps": []
        }
    }
}