Programming Basics

EdgeX-API programming interface is based on REST API and EdgeX convention. Essential knowledge of both is helpful for EdgeX-API programming.

Content

• Device service API programming

• Verify device service APIs

• Reference

Device Service API Programming

API Convention

For EdgeX device service's RESTful APIs, it usually uses two parameters, device and command.

• Device: represents physical device or resource, for example battery, disk, Wi-Fi...

• Command: represents physical sensor node or single I/O port, for example, battery temperature, disk total capacity, Wi-Fi's IP...

In each device service's APIs, it will list the supported devices and names.

EdgeX Device service uses two options to specify the device and commands. One is by ID (generated by database) and other one is by name.

URL Call by ID

http://localhost:48082/api/v1/device/{deviceId}/command/{commandId}

URL Call by name

http://localhost:49987/api/v1/device/name/{deviceName}/{commandName}

Note: the port 49987 depends on the device service.

URL Call by ID

For the one by ID, EdgeX provides the following REST API to get device and command ID

http://localhost:48082/api/v1/device

Note: localhost is replaced by the physical device IP.

In the above example, for Advantech-IPSM90-01 device

• deviceId is 5cb809a79f8fc20001ddad32 and

• Battery_Temperature’s commandId is 5cb809a79f8fc20001ddace8.

Replace "edgex-core-command" with physical device IP (for example 172.16.8.87) and use web browser to send the following command to get Advantech-IPSM90-01’s Battery_Temperature.

http://172.16.8.87:48082/api/v1/device/5cb809a79f8fc20001ddad32/command/5cb809a79f8fc20001ddace8

Examples

Get temperature from Advantech-IPSM90-01 by device ID

http://172.16.8.87:48082/api/v1/device/5cb809a79f8fc20001ddad32/command/5cb809a79f8fc20001ddace8

Get temperature from Advantech-IPSM90-01 by device name

http://172.16.8.87:49987/api/v1/device/name/Advantech-IPSM90-01/Battery_Temperature

Response

HTTP response code

• Success Response:

Code: 200

• Error Response:

Code: 503
Content: service unavailable

• Success Content Example (GET)

​ device field: the specified device name name: the specified command name value: returned value for the specified device and command

Verify Device Service APIs

There are two ways to verify device service APIs or RESTful APIs, cURL tool or Postman tool.

Example: verify the API to get temperature from Advantech-IPSM90-01 by device name

cURL

The following example use curl tool to set Battery_AlertStatus to 1

curl -X PUT -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"Battery_AlertStatus":"1"}' "http://172.16.8.87:48082/api/v1/device/5cb809a79f8fc20001ddad34/command/5cb809a79f8fc20001ddcfe"

Postman

Input the fields

• method: GET (on the top left)

• URL: http://172.16.9.226:49987/api/v1/device/name/Advantech-IPSM90-01/Battery_Temperature

Then press "Send" button. The result is shown as below

• Status: 200 OK

• value: 28 (in the response Body field below)

Reference

• Postman download link: https://www.getpostman.com/downloads/

• cURL installation and using cURL: https://develop.zendesk.com/hc/en-us/articles/360001068567-Installing-and-using-cURL#install