REST example

The REST Device Service is intended to work with third-party services, allowing these services to input binary data into Edge Xpert.

The REST Device Service starts with three sample device profiles and devices preloaded. This example will use one of these sample devices: sample-image.

Start the REST Device Service

To start the REST Device Service, enter the following command:

edgexpert up device-rest

Device Onboarding

Once the REST Device Service has been started, REST devices can be onboarded to Edge Xpert using either the Edge Xpert Manager UI or through Edge Xpert REST API commands. Instructions on how to use both methods are described below.

Device Onboarding with the Edge Xpert Manager UI

1. Start Edge Xpert Manager UI:

   edgexpert up xpert-manager
   

2. Open a browser and go to localhost:9090. The default username and password is admin

3. Using the device profile upload capability, upload the provided example device profile at /usr/share/edgexpert/examples/device-services/rest/sample-image-device.yaml

4. Onboard the REST device using the device onboarding capability. The following values can be used to provision the example REST device:

   Field	Example Value	Description	Required
   Name	sample-image	Unique name used to identify device	Required
   Description	RESTful Device that sends in binary image data	Additional information about the device	Optional
   Label	"rest", "binary", "image"	Additional information about the device	Optional
   Protocol	rest	The name of the protocol	Required
   Device Profile	sample-image	The name of the device profile uploaded above	Required
   Device Service	device-rest	The name of the appropriate device service	Required

Device Onboarding with the Edge Xpert REST API

1. Upload the provided REST example device profile:

   curl http://localhost:59881/api/v2/deviceprofile/uploadfile -F "file=@/usr/share/edgexpert/examples/device-services/rest/sample-image-device.yaml"
   

2. Onboard the device using similar values as explained above:

   curl -X 'POST' \
     'http://localhost:59881/api/v2/device' \
     -H 'Content-Type: application/json' \
     -d '[
     {
       "apiVersion": "v2",
       "device": {
         "name": "sample-image",
         "description": "RESTful Device that sends in binary image data",
         "adminState": "UNLOCKED",
         "operatingState": "UP",
         "labels": [
           "rest",
           "binary",
           "image"
         ],
         "serviceName": "device-rest",
         "profileName": "sample-image",
         "protocolName": "rest",
         "protocols": {
           "other": {}
         }
       }
     }
   ]'
   

Uploading binary data

The REST Device Service functions differently than other Edge Xpert device services. As such, it does not use PUT requests to control data. Instead, POST requests are issued to input the binary data.

Using a REST API application, such as Postman, is recommended to post this data. See the example below:

Alternatively, a cURL can be used, for example:

curl --request POST --header 'Content-Type: image/jpeg' \
--data-binary '@/path/to/image/image.jpg' \
'http://localhost:59986/api/v2/resource/sample-image/jpeg'  

See the Core Command Microservice for more information on POST commands.