diff --git a/docs_src/examples/Ch-CommandingDeviceThroughRulesEngine.md b/docs_src/examples/Ch-CommandingDeviceThroughRulesEngine.md index 403a5ddec9..712d173533 100644 --- a/docs_src/examples/Ch-CommandingDeviceThroughRulesEngine.md +++ b/docs_src/examples/Ch-CommandingDeviceThroughRulesEngine.md @@ -38,14 +38,14 @@ curl -X POST \ Since both use case scenario rules will send commands to the `Random-Boolean-Device` virtual device, use the curl request below to get a list of available commands for this device. ``` bash -curl http://127.0.0.1:59882/api/v2/device/name/Random-Boolean-Device | jq +curl http://127.0.0.1:59882/api/v3/device/name/Random-Boolean-Device | jq ``` It should print results like those below. ``` json { - "apiVersion": "v2", + "apiVersion": "v3", "statusCode": 200, "deviceCoreCommand": { "deviceName": "Random-Boolean-Device", @@ -54,7 +54,7 @@ It should print results like those below. { "name": "WriteBoolValue", "set": true, - "path": "/api/v2/device/name/Random-Boolean-Device/WriteBoolValue", + "path": "/api/v3/device/name/Random-Boolean-Device/WriteBoolValue", "url": "http://edgex-core-command:59882", "parameters": [ { @@ -70,7 +70,7 @@ It should print results like those below. { "name": "WriteBoolArrayValue", "set": true, - "path": "/api/v2/device/name/Random-Boolean-Device/WriteBoolArrayValue", + "path": "/api/v3/device/name/Random-Boolean-Device/WriteBoolArrayValue", "url": "http://edgex-core-command:59882", "parameters": [ { @@ -87,7 +87,7 @@ It should print results like those below. "name": "Bool", "get": true, "set": true, - "path": "/api/v2/device/name/Random-Boolean-Device/Bool", + "path": "/api/v3/device/name/Random-Boolean-Device/Bool", "url": "http://edgex-core-command:59882", "parameters": [ { @@ -100,7 +100,7 @@ It should print results like those below. "name": "BoolArray", "get": true, "set": true, - "path": "/api/v2/device/name/Random-Boolean-Device/BoolArray", + "path": "/api/v3/device/name/Random-Boolean-Device/BoolArray", "url": "http://edgex-core-command:59882", "parameters": [ { @@ -123,7 +123,7 @@ You can test calling this command with its parameters using curl as shown below. ``` bash curl -X PUT \ - http://edgex-core-command:59882/api/v2/device/name/Random-Boolean-Device/WriteBoolValue \ + http://edgex-core-command:59882/api/v3/device/name/Random-Boolean-Device/WriteBoolValue \ -H 'Content-Type: application/json' \ -d '{"Bool":"true", "EnableRandomization_Bool": "true"}' ``` @@ -146,7 +146,7 @@ curl -X POST \ "actions": [ { "rest": { - "url": "http://edgex-core-command:59882/api/v2/device/name/Random-Boolean-Device/WriteBoolValue", + "url": "http://edgex-core-command:59882/api/v3/device/name/Random-Boolean-Device/WriteBoolValue", "method": "put", "dataTemplate": "{\"Bool\":\"true\", \"EnableRandomization_Bool\": \"true\"}", "sendSingle": true @@ -173,7 +173,7 @@ curl -X POST \ "actions": [ { "rest": { - "url": "http://edgex-core-command:59882/api/v2/device/name/Random-Boolean-Device/WriteBoolValue", + "url": "http://edgex-core-command:59882/api/v3/device/name/Random-Boolean-Device/WriteBoolValue", "method": "put", "dataTemplate": "{\"Bool\":\"false\", \"EnableRandomization_Bool\": \"false\"}", "sendSingle": true diff --git a/docs_src/examples/Ch-ExamplesAddingMQTTDevice.md b/docs_src/examples/Ch-ExamplesAddingMQTTDevice.md index 86066897fc..33ca9c77e0 100644 --- a/docs_src/examples/Ch-ExamplesAddingMQTTDevice.md +++ b/docs_src/examples/Ch-ExamplesAddingMQTTDevice.md @@ -308,7 +308,7 @@ Now we're ready to run some commands. Use the following query to find executable commands: ```json -$ curl http://localhost:59882/api/v2/device/all | json_pp +$ curl http://localhost:59882/api/v3/device/all | json_pp { "deviceCoreCommands" : [ @@ -318,7 +318,7 @@ $ curl http://localhost:59882/api/v2/device/all | json_pp { "name" : "values", "get" : true, - "path" : "/api/v2/device/name/my-custom-device/values", + "path" : "/api/v3/device/name/my-custom-device/values", "url" : "http://edgex-core-command:59882", "parameters" : [ { @@ -345,14 +345,14 @@ $ curl http://localhost:59882/api/v2/device/all | json_pp ], "name" : "message", "get" : true, - "path" : "/api/v2/device/name/my-custom-device/message", + "path" : "/api/v3/device/name/my-custom-device/message", "set" : true }, { "name": "json", "get": true, "set": true, - "path": "/api/v2/device/name/MQTT-test-device/json", + "path": "/api/v3/device/name/MQTT-test-device/json", "url" : "http://edgex-core-command:59882", "parameters": [ { @@ -376,7 +376,7 @@ Execute a SET command according to the url and parameterNames, replacing \[host\] with the server IP when running the SET command. ``` -$ curl http://localhost:59882/api/v2/device/name/my-custom-device/message \ +$ curl http://localhost:59882/api/v3/device/name/my-custom-device/message \ -H "Content-Type:application/json" -X PUT \ -d '{"message":"Hello!"}' ``` @@ -386,7 +386,7 @@ $ curl http://localhost:59882/api/v2/device/name/my-custom-device/message \ Execute a GET command as follows: ```json -$ curl http://localhost:59882/api/v2/device/name/my-custom-device/message | json_pp +$ curl http://localhost:59882/api/v3/device/name/my-custom-device/message | json_pp { "apiVersion":"v2", @@ -429,7 +429,7 @@ show that the service auto-executes the command every 30 secs, as shown below: ```json -$ curl http://localhost:59880/api/v2/reading/resourceName/message | json_pp +$ curl http://localhost:59880/api/v3/reading/resourceName/message | json_pp { "statusCode" : 200, @@ -474,7 +474,7 @@ The following results show that the mock device sent the reading every 15 secs: ```json -$ curl http://localhost:59880/api/v2/reading/resourceName/randnum | json_pp +$ curl http://localhost:59880/api/v3/reading/resourceName/randnum | json_pp { "readings" : [ diff --git a/docs_src/examples/Ch-ExamplesAddingModbusDevice.md b/docs_src/examples/Ch-ExamplesAddingModbusDevice.md index 8fbd0322d8..2fde9cb44c 100644 --- a/docs_src/examples/Ch-ExamplesAddingModbusDevice.md +++ b/docs_src/examples/Ch-ExamplesAddingModbusDevice.md @@ -299,12 +299,12 @@ To add a device after starting the services, complete the following steps: 1. Upload the device profile above to metadata with a POST to - and add the + and add the file as key "file" to the body in form-data format, and the created ID will be returned. The following example command uses curl to send the request: ``` - $ curl http://localhost:59881/api/v2/deviceprofile/uploadfile \ + $ curl http://localhost:59881/api/v3/deviceprofile/uploadfile \ -F "file=@temperature.profile.yml" ``` @@ -312,13 +312,13 @@ steps: below to match if necessary or if using other device services. 4. Add the device with a POST to - , the body will look something + , the body will look something like: ``` - $ curl http://localhost:59881/api/v2/device -H "Content-Type:application/json" -X POST \ + $ curl http://localhost:59881/api/v3/device -H "Content-Type:application/json" -X POST \ -d '[ { - "apiVersion": "v2", + "apiVersion": "v3", "device": { "name" :"Modbus-TCP-Temperature-Sensor", "description":"This device is a product for monitoring the temperature via the ethernet", @@ -363,7 +363,7 @@ Now we're ready to run some commands. Use the following query to find executable commands: ```json -$ curl http://localhost:59882/api/v2/device/all | json_pp +$ curl http://localhost:59882/api/v3/device/all | json_pp { "apiVersion" : "v2", @@ -387,14 +387,14 @@ $ curl http://localhost:59882/api/v2/device/all | json_pp "resourceName" : "ThermostatH" } ], - "path" : "/api/v2/device/name/Modbus-TCP-Temperature-Sensor/AlarmThreshold" + "path" : "/api/v3/device/name/Modbus-TCP-Temperature-Sensor/AlarmThreshold" }, { "get" : true, "url" : "http://edgex-core-command:59882", "name" : "AlarmMode", "set" : true, - "path" : "/api/v2/device/name/Modbus-TCP-Temperature-Sensor/AlarmMode", + "path" : "/api/v3/device/name/Modbus-TCP-Temperature-Sensor/AlarmMode", "parameters" : [ { "resourceName" : "AlarmMode", @@ -406,7 +406,7 @@ $ curl http://localhost:59882/api/v2/device/all | json_pp "get" : true, "url" : "http://edgex-core-command:59882", "name" : "Temperature", - "path" : "/api/v2/device/name/Modbus-TCP-Temperature-Sensor/Temperature", + "path" : "/api/v3/device/name/Modbus-TCP-Temperature-Sensor/Temperature", "parameters" : [ { "valueType" : "Float32", @@ -427,7 +427,7 @@ $ curl http://localhost:59882/api/v2/device/all | json_pp Execute SET command according to `url` and `parameterNames`, replacing [host] with the server IP when running the SET command. ``` -$ curl http://localhost:59882/api/v2/device/name/Modbus-TCP-Temperature-Sensor/AlarmThreshold \ +$ curl http://localhost:59882/api/v3/device/name/Modbus-TCP-Temperature-Sensor/AlarmThreshold \ -H "Content-Type:application/json" -X PUT \ -d '{"ThermostatL":"15","ThermostatH":"100"}' ``` @@ -437,7 +437,7 @@ $ curl http://localhost:59882/api/v2/device/name/Modbus-TCP-Temperature-Sensor/A Replace *\* with the server IP when running the GET command. ```json -$ curl http://localhost:59882/api/v2/device/name/Modbus-TCP-Temperature-Sensor/AlarmThreshold | json_pp +$ curl http://localhost:59882/api/v3/device/name/Modbus-TCP-Temperature-Sensor/AlarmThreshold | json_pp { "statusCode" : 200, @@ -491,7 +491,7 @@ After service startup, query core-data's API. The results show that the service auto-executes the command every 30 seconds. ```json -$ curl http://localhost:59880/api/v2/event/device/name/Modbus-TCP-Temperature-Sensor | json_pp +$ curl http://localhost:59880/api/v3/event/device/name/Modbus-TCP-Temperature-Sensor | json_pp { "events" : [ @@ -673,17 +673,17 @@ $ docker-compose up -d ``` 2. Upload the device profile ``` - $ curl http://localhost:59881/api/v2/deviceprofile/uploadfile \ + $ curl http://localhost:59881/api/v3/deviceprofile/uploadfile \ -F "file=@modbus.rtu.demo.profile.yml" ``` 3. Create the device entity to the EdgeX. You can find the Modbus RTU setting on the device or the user manual. ```json - $ curl http://localhost:59881/api/v2/device -H "Content-Type:application/json" -X POST \ + $ curl http://localhost:59881/api/v3/device -H "Content-Type:application/json" -X POST \ -d '[ { - "apiVersion": "v2", + "apiVersion": "v3", "device": { "name" :"Modbus-RTU-IO-Module", "description":"The device can be used to monitor the status of the digital input and digital output channels.", diff --git a/docs_src/examples/Ch-ExamplesAddingSNMPDevice.md b/docs_src/examples/Ch-ExamplesAddingSNMPDevice.md index 1c932591fe..31a2899a20 100644 --- a/docs_src/examples/Ch-ExamplesAddingSNMPDevice.md +++ b/docs_src/examples/Ch-ExamplesAddingSNMPDevice.md @@ -111,7 +111,7 @@ Because setting a light or buzzer requires both of the control state and timer O You will need to upload this profile into core metadata. Download the [Patlite device profile](patlite-snmp.yml) to a convenient directory. Then, using the following `curl` command, request the profile be uploaded into core metadata. ``` Shell -curl -X 'POST' 'http://localhost:59881/api/v2/deviceprofile/uploadfile' --form 'file=@"/home/yourfilelocationhere/patlite-snmp.yml"' +curl -X 'POST' 'http://localhost:59881/api/v3/deviceprofile/uploadfile' --form 'file=@"/home/yourfilelocationhere/patlite-snmp.yml"' ``` !!! Alert @@ -127,7 +127,7 @@ The curl command to POST the new Patlite device (named `patlite1`) into metadata ``` Shell -curl -X 'POST' 'http://localhost:59881/api/v2/device' -d '[{"apiVersion": "v2", "device": {"name": "patlite1","description": "patlite #1","adminState": "UNLOCKED","operatingState": "UP","labels": ["patlite"],"serviceName": "device-snmp","profileName": "patlite-snmp-profile","protocols": {"TCP": {"Address": "10.0.0.14","Port": "161"}}, "AutoEvents":[{"Interval":"10s","OnChange":true,"SourceName":"RedLightCurrentState"}, {"Interval":"10s","OnChange":true,"SourceName":"GreenLightCurrentState"}, {"Interval":"10s","OnChange":true,"SourceName":"AmberLightCurrentState"}, {"Interval":"10s","OnChange":true,"SourceName":"BuzzerCurrentState"}]}}]' +curl -X 'POST' 'http://localhost:59881/api/v3/device' -d '[{"apiVersion": "v3", "device": {"name": "patlite1","description": "patlite #1","adminState": "UNLOCKED","operatingState": "UP","labels": ["patlite"],"serviceName": "device-snmp","profileName": "patlite-snmp-profile","protocols": {"TCP": {"Address": "10.0.0.14","Port": "161"}}, "AutoEvents":[{"Interval":"10s","OnChange":true,"SourceName":"RedLightCurrentState"}, {"Interval":"10s","OnChange":true,"SourceName":"GreenLightCurrentState"}, {"Interval":"10s","OnChange":true,"SourceName":"AmberLightCurrentState"}, {"Interval":"10s","OnChange":true,"SourceName":"BuzzerCurrentState"}]}}]' ``` !!! Info @@ -143,7 +143,7 @@ If the device service is up and running and the profile and device have been add To get the current state of a light (in the example below the `Green` light), make a curl request like the following of the command service. ``` Shell -curl 'http://localhost:59882/api/v2/device/name/patlite1/GreenLightCurrentState' | json_pp +curl 'http://localhost:59882/api/v3/device/name/patlite1/GreenLightCurrentState' | json_pp ``` !!! Alert @@ -193,7 +193,7 @@ The results should look something like that below. To turn a signal tower light or the buzzer on, you can issue a PUT device command via the core command service. The example below turns on the `Green` light. ``` Shell -curl --location --request PUT 'http://localhost:59882/api/v2/device/name/patlite1/GreenLight' --header 'cont: application/json' --data-raw '{"GreenLightControlState":"2","GreenLightTimer":"0"}' +curl --location --request PUT 'http://localhost:59882/api/v3/device/name/patlite1/GreenLight' --header 'cont: application/json' --data-raw '{"GreenLightControlState":"2","GreenLightTimer":"0"}' ``` ![image](EdgeX_Patlite_Green_On.jpg) diff --git a/docs_src/examples/Ch-ExamplesSendingAndConsumingBinary.md b/docs_src/examples/Ch-ExamplesSendingAndConsumingBinary.md index de8369b43c..021395d99c 100644 --- a/docs_src/examples/Ch-ExamplesSendingAndConsumingBinary.md +++ b/docs_src/examples/Ch-ExamplesSendingAndConsumingBinary.md @@ -55,7 +55,7 @@ if req.DeviceResourceName == "camera_snapshot" { Querying core-metadata for the Device's Commands and DeviceName provides the following as the URL to request a reading from the snapshot command: - + Unlike with non-binary Events, making a request to this URL will return an event in CBOR representation. CBOR is a representation of binary data diff --git a/docs_src/examples/Ch-ExamplesVirtualDeviceService.md b/docs_src/examples/Ch-ExamplesVirtualDeviceService.md index 01b2a4fb8e..7572fbb9a1 100644 --- a/docs_src/examples/Ch-ExamplesVirtualDeviceService.md +++ b/docs_src/examples/Ch-ExamplesVirtualDeviceService.md @@ -34,19 +34,19 @@ If you're going to download the source code and run the virtual device service i The virtual device service is configured to send simulated data to core data every few seconds (from 10-30 seconds depending on device - see the [device configuration file](https://github.com/edgexfoundry/device-virtual-go/blob/{{version}}/cmd/res/devices/devices.yaml) for AutoEvent details). You can exercise the `GET` request on the command service to see the generated value produced by any of the virtual device's simulated devices. Use the curl command below to exercise the virtual device service API (via core command service). ``` bash -curl -X GET localhost:59882/api/v2/device/name/Random-Integer-Device/Int8 +curl -X GET localhost:59882/api/v3/device/name/Random-Integer-Device/Int8 ``` !!! Warning - The example above assumes your core command service is available on `localhost` at the default service port of 59882. Also, you must replace your device name and command name in the example above with your virtual device service's identifiers. If you are not sure of the identifiers to use, query the command service for the full list of commands and devices at `http://localhost:59882/api/v2/device/all`. + The example above assumes your core command service is available on `localhost` at the default service port of 59882. Also, you must replace your device name and command name in the example above with your virtual device service's identifiers. If you are not sure of the identifiers to use, query the command service for the full list of commands and devices at `http://localhost:59882/api/v3/device/all`. The virtual device should respond (via the core command service) with event/reading JSON similar to that below. ``` json { - "apiVersion": "v2", + "apiVersion": "v3", "statusCode": 200, "event": { - "apiVersion": "v2", + "apiVersion": "v3", "id": "3beb5b83-d923-4c8a-b949-c1708b6611c1", "deviceName": "Random-Integer-Device", "profileName": "Random-Integer-Device", @@ -75,7 +75,7 @@ The virtual devices managed by the virtual device can also be actuated. The vir Below is example actuation of one of the virtual devices. In this example, it sets the fixed `GET` return value to 123 and turns off random generation. ``` bash -curl -X PUT -d '{"Int8": "123", "EnableRandomization_Int8": "false"}' localhost:59882/api/v2/device/name/Random-Integer-Device/Int8 +curl -X PUT -d '{"Int8": "123", "EnableRandomization_Int8": "false"}' localhost:59882/api/v3/device/name/Random-Integer-Device/Int8 ``` !!! Note @@ -84,7 +84,7 @@ curl -X PUT -d '{"Int8": "123", "EnableRandomization_Int8": "false"}' localhost: Return the virtual device to randomly generating numbers with another `PUT` call. ``` bash -curl -X PUT -d '{"EnableRandomization_Int8": "true"}' localhost:59882/api/v2/device/name/Random-Integer-Device/Int8 +curl -X PUT -d '{"EnableRandomization_Int8": "true"}' localhost:59882/api/v3/device/name/Random-Integer-Device/Int8 ``` ## Reference diff --git a/docs_src/examples/commands_MQTT.png b/docs_src/examples/commands_MQTT.png deleted file mode 100644 index c0db63679d..0000000000 Binary files a/docs_src/examples/commands_MQTT.png and /dev/null differ diff --git a/docs_src/examples/config_changes_MQTT.png b/docs_src/examples/config_changes_MQTT.png deleted file mode 100644 index 5ceabd121d..0000000000 Binary files a/docs_src/examples/config_changes_MQTT.png and /dev/null differ diff --git a/docs_src/examples/configuration.png b/docs_src/examples/configuration.png deleted file mode 100644 index 9e3ee1dc0f..0000000000 Binary files a/docs_src/examples/configuration.png and /dev/null differ diff --git a/docs_src/examples/configuration_MQTT.png b/docs_src/examples/configuration_MQTT.png deleted file mode 100644 index a72816ee29..0000000000 Binary files a/docs_src/examples/configuration_MQTT.png and /dev/null differ diff --git a/docs_src/examples/connection.png b/docs_src/examples/connection.png deleted file mode 100644 index b0fdfb5535..0000000000 Binary files a/docs_src/examples/connection.png and /dev/null differ diff --git a/docs_src/examples/devicegoSetup.png b/docs_src/examples/devicegoSetup.png deleted file mode 100644 index 3f115c76e1..0000000000 Binary files a/docs_src/examples/devicegoSetup.png and /dev/null differ diff --git a/docs_src/examples/deviceprofile.png b/docs_src/examples/deviceprofile.png deleted file mode 100644 index 1ccae76494..0000000000 Binary files a/docs_src/examples/deviceprofile.png and /dev/null differ diff --git a/docs_src/getting-started/ApplicationFunctionsSDK.md b/docs_src/getting-started/ApplicationFunctionsSDK.md index 49bfee5698..1e83d7be40 100644 --- a/docs_src/getting-started/ApplicationFunctionsSDK.md +++ b/docs_src/getting-started/ApplicationFunctionsSDK.md @@ -104,14 +104,14 @@ Set the Trigger type to `http` in configuration file found here: [res/configurat Type="http" ``` -Using PostMan or curl send the following JSON to `localhost:/api/v2/trigger` +Using PostMan or curl send the following JSON to `localhost:/api/v3/trigger` ```json { "requestId": "82eb2e26-0f24-48ba-ae4c-de9dac3fb9bc", - "apiVersion": "v2", + "apiVersion": "v3", "event": { - "apiVersion": "v2", + "apiVersion": "v3", "deviceName": "Random-Float-Device", "profileName": "Random-Float-Device", "sourceName" : "Float32", @@ -119,7 +119,7 @@ Using PostMan or curl send the following JSON to `localhost:/api/v2/trigge "id": "94eb2e26-0f24-5555-2222-de9dac3fb228", "readings": [ { - "apiVersion": "v2", + "apiVersion": "v3", "resourceName": "Float32", "profileName": "Random-Float-Device", "deviceName": "Random-Float-Device", diff --git a/docs_src/getting-started/Ch-GettingStartedDTOValidation.md b/docs_src/getting-started/Ch-GettingStartedDTOValidation.md index 96737d48df..d6152bd920 100644 --- a/docs_src/getting-started/Ch-GettingStartedDTOValidation.md +++ b/docs_src/getting-started/Ch-GettingStartedDTOValidation.md @@ -33,4 +33,4 @@ This validation allows for only the following characters: - special character: - _ ~ : ; = !!! edgey "EdgeX 3.0" - In EdgeX 3.0, the character restriction was reduced for the command name and resource name because some protocols may use `/` or `.` in the name. By using URL escaping for the API, device command name and resource name allow various characters. For example, the user can define the command name `line-a/test:value` and use it with URL escaping as `/api/v2/device/name/Modbus-TCP-Device/line-a%2Ftest%3Avalue`. + In EdgeX 3.0, the character restriction was reduced for the command name and resource name because some protocols may use `/` or `.` in the name. By using URL escaping for the API, device command name and resource name allow various characters. For example, the user can define the command name `line-a/test:value` and use it with URL escaping as `/api/v3/device/name/Modbus-TCP-Device/line-a%2Ftest%3Avalue`. diff --git a/docs_src/getting-started/Ch-GettingStartedDockerUsers.md b/docs_src/getting-started/Ch-GettingStartedDockerUsers.md index 8ac6475d26..f7e0dde576 100644 --- a/docs_src/getting-started/Ch-GettingStartedDockerUsers.md +++ b/docs_src/getting-started/Ch-GettingStartedDockerUsers.md @@ -168,7 +168,7 @@ When you are done reviewing the content of the log, select **Control-c** to stop Each EdgeX micro service has a built-in response to a "ping" HTTP request. In networking environments, use a [ping request](https://techterms.com/definition/ping) to check the reach-ability of a network resource. EdgeX uses the same concept to check the availability or reach-ability of a micro service. After the EdgeX micro service containers are running, you can "ping" any one of the micro services to check that it is running. Open a browser or HTTP REST client tool and use the service's ping address (outlined below) to check that is available. ``` -http://localhost:[service port]/api/v2/ping +http://localhost:[service port]/api/v3/ping ``` See [EdgeX Default Service Ports](../../general/ServicePorts) for a list of the EdgeX default service ports. diff --git a/docs_src/getting-started/Ch-GettingStartedGoDevelopers.md b/docs_src/getting-started/Ch-GettingStartedGoDevelopers.md index 94ad04d0c4..9eb2e177df 100644 --- a/docs_src/getting-started/Ch-GettingStartedGoDevelopers.md +++ b/docs_src/getting-started/Ch-GettingStartedGoDevelopers.md @@ -168,7 +168,7 @@ While the EdgeX services are running you can make EdgeX API calls to `localhost` Each EdgeX micro service has a built-in respond to a "ping" HTTP request. In networking environments, use a [ping request](https://techterms.com/definition/ping) to check the reach-ability of a network resource. EdgeX uses the same concept to check the availability or reach-ability of a micro service. After the EdgeX micro services are running, you can "ping" any one of the micro services to check that it is running. Open a browser or HTTP REST client tool and use the service's ping address (outlined below) to check that is available. ``` -http://localhost:[port]/api/v2/ping +http://localhost:[port]/api/v3/ping ``` See [EdgeX Default Service Ports](../../general/ServicePorts) for a list of the EdgeX default service ports. @@ -219,4 +219,4 @@ With all the micro services built, you can now run EdgeX services. You may first ![image](EdgeX_GoLandMakeRun.png) -You can now call on the service APIs to make sure they are running correctly. Namely, call on `http://localhost:\[service port\]/api/v2/ping` to see each service respond to the simplest of requests. +You can now call on the service APIs to make sure they are running correctly. Namely, call on `http://localhost:\[service port\]/api/v3/ping` to see each service respond to the simplest of requests. diff --git a/docs_src/getting-started/Ch-GettingStartedHybrid.md b/docs_src/getting-started/Ch-GettingStartedHybrid.md index 0abce5afca..2fea41e73b 100644 --- a/docs_src/getting-started/Ch-GettingStartedHybrid.md +++ b/docs_src/getting-started/Ch-GettingStartedHybrid.md @@ -86,7 +86,7 @@ Give the virtual device a few seconds or so to initialize itself and start sendi to check that events are being deposited. You can do this by calling on the Core Data API that checks the count of events in Core Data. ``` -http://localhost:59880/api/v2/event/count +http://localhost:59880/api/v3/event/count ``` ![image](EdgeX_GettingStartedHybridResults.png) diff --git a/docs_src/getting-started/Ch-GettingStartedSDK-C.md b/docs_src/getting-started/Ch-GettingStartedSDK-C.md index 4492d4db59..c6e205c54e 100644 --- a/docs_src/getting-started/Ch-GettingStartedSDK-C.md +++ b/docs_src/getting-started/Ch-GettingStartedSDK-C.md @@ -229,13 +229,13 @@ sends to EdgeX. service directly: ``` bash - curl 0:59992/api/v2/device/name/RandNum-Device01/RandomNumber + curl 0:59992/api/v3/device/name/RandNum-Device01/RandomNumber ``` 6. Using a browser, enter the following URL to see the event/reading data that the service is generating and sending to EdgeX: - + This request asks core data to provide the last 100 events/readings associated to the RandNum-Device-01. diff --git a/docs_src/getting-started/Ch-GettingStartedSDK-Go.md b/docs_src/getting-started/Ch-GettingStartedSDK-Go.md index d52ac6aa69..eefd9d211c 100644 --- a/docs_src/getting-started/Ch-GettingStartedSDK-Go.md +++ b/docs_src/getting-started/Ch-GettingStartedSDK-Go.md @@ -210,7 +210,7 @@ Follow these steps to create a pre-defined device for the simple random number g ### Validating your Device -Go Device Services provide `/api/v2/validate/device` API to validate device's ProtocolProperties. +Go Device Services provide `/api/v3/validate/device` API to validate device's ProtocolProperties. This feature allows Device Services whose protocol has strict rule to validate their devices before adding them into EdgeX. Go SDK provides `DeviceValidator` interface: @@ -374,7 +374,7 @@ sends to EdgeX: 3. Using a browser, enter the following URL to see the event/reading data that the service is generating and sending to EdgeX: - + This request asks core data to provide the events associated to the RandNum-Device-01. diff --git a/docs_src/getting-started/native/ZeroMQCheck-arm.png b/docs_src/getting-started/native/ZeroMQCheck-arm.png deleted file mode 100644 index 2efe4546f0..0000000000 Binary files a/docs_src/getting-started/native/ZeroMQCheck-arm.png and /dev/null differ diff --git a/docs_src/getting-started/native/ZeroMQCheck.png b/docs_src/getting-started/native/ZeroMQCheck.png deleted file mode 100644 index f53a440f07..0000000000 Binary files a/docs_src/getting-started/native/ZeroMQCheck.png and /dev/null differ diff --git a/docs_src/getting-started/quick-start/index.md b/docs_src/getting-started/quick-start/index.md index 127e0a09b2..de2f5fada9 100644 --- a/docs_src/getting-started/quick-start/index.md +++ b/docs_src/getting-started/quick-start/index.md @@ -71,7 +71,7 @@ curl http://localhost:59882/api/v2/device/name/Random-Integer-Device This will return a lot of JSON, because there are a number of commands you can call on this device, but the commands we're going to use in this guide are `Int16` (the comand to get the current integer 16 value) and `WriteInt16Value` (the command to disable the generation of the random integer 16 number and specify the integer value to return). Look for the `Int16` and `WriteInt16Value` commands like those shown in the JSON as below: ``` json { - "apiVersion": "v2", + "apiVersion": "v3", "statusCode": 200, "deviceCoreCommand": { "deviceName": "Random-Integer-Device", @@ -122,10 +122,10 @@ curl http://localhost:59882/api/v2/device/name/Random-Integer-Device/Int16 This command will return a JSON result that looks like this: ``` json { - "apiVersion": "v2", + "apiVersion": "v3", "statusCode": 200, "event": { - "apiVersion": "v2", + "apiVersion": "v3", "id": "6d829637-730c-4b70-9208-dc179070003f", "deviceName": "Random-Integer-Device", "profileName": "Random-Integer-Device", diff --git a/docs_src/getting-started/random-generator-device.toml b/docs_src/getting-started/random-generator-device.toml deleted file mode 100644 index d3eb548ad2..0000000000 --- a/docs_src/getting-started/random-generator-device.toml +++ /dev/null @@ -1,14 +0,0 @@ -# Pre-define Devices -[[DeviceList]] - Name = 'RandNum-Device01' - ProfileName = 'RandNum-Device' - Description = 'Random Number Generator Device' - Labels = [ 'random', 'test' ] - [DeviceList.Protocols] - [DeviceList.Protocols.Other] - Address = 'random' - Port = '300' - [[DeviceList.AutoEvents]] - Interval = '10s' - SourceName = 'RandomNumber' - OnChange = false diff --git a/docs_src/getting-started/tools/create-device.png b/docs_src/getting-started/tools/create-device.png deleted file mode 100644 index 753a959fcb..0000000000 Binary files a/docs_src/getting-started/tools/create-device.png and /dev/null differ diff --git a/docs_src/getting-started/tools/device-list-by-name.png b/docs_src/getting-started/tools/device-list-by-name.png deleted file mode 100644 index 065c89bf2f..0000000000 Binary files a/docs_src/getting-started/tools/device-list-by-name.png and /dev/null differ diff --git a/docs_src/getting-started/tools/device-list-json.png b/docs_src/getting-started/tools/device-list-json.png deleted file mode 100644 index 80846b14f3..0000000000 Binary files a/docs_src/getting-started/tools/device-list-json.png and /dev/null differ diff --git a/docs_src/getting-started/tools/device-list.png b/docs_src/getting-started/tools/device-list.png deleted file mode 100644 index 1d56c6983b..0000000000 Binary files a/docs_src/getting-started/tools/device-list.png and /dev/null differ diff --git a/docs_src/microservices/application/AdvancedTopics.md b/docs_src/microservices/application/AdvancedTopics.md index 5abf78672e..55979da0b7 100644 --- a/docs_src/microservices/application/AdvancedTopics.md +++ b/docs_src/microservices/application/AdvancedTopics.md @@ -10,11 +10,11 @@ This SDK provides the capability to define the functions pipeline via configurat It is not uncommon to require your own custom REST endpoints when building an Application Service. Rather than spin up your own webserver inside of your app (alongside the already existing running webserver), we've exposed a method that allows you add your own routes to the existing webserver. A few routes are reserved and cannot be used: -- /api/v2/version -- /api/v2/ping -- /api/v2/config -- /api/v2/trigger -- /api/v2/secret +- /api/v3/version +- /api/v3/ping +- /api/v3/config +- /api/v3/trigger +- /api/v3/secret To add your own route, use the `AddRoute()` API provided on the `ApplicationService` interface. @@ -281,7 +281,7 @@ All instances of App Services running in secure mode require a SecretStore to be ##### Secure Mode -When running an application service in secure mode, secrets can be stored in the service's secure SecretStore by making an HTTP `POST` call to the `/api/v2/secret` API route in the application service. The secret data POSTed is stored and retrieved from the service's secure SecretStore . Once a secret is stored, only the service that added the secret will be able to retrieve it. For secret retrieval see [Getting Secrets](#getting-secrets) section below. +When running an application service in secure mode, secrets can be stored in the service's secure SecretStore by making an HTTP `POST` call to the `/api/v3/secret` API route in the application service. The secret data POSTed is stored and retrieved from the service's secure SecretStore . Once a secret is stored, only the service that added the secret will be able to retrieve it. For secret retrieval see [Getting Secrets](#getting-secrets) section below. !!! example "Example - JSON message body" ```json diff --git a/docs_src/microservices/application/AppServiceConfigurable.md b/docs_src/microservices/application/AppServiceConfigurable.md index 111f7c8662..e23f020baa 100644 --- a/docs_src/microservices/application/AppServiceConfigurable.md +++ b/docs_src/microservices/application/AppServiceConfigurable.md @@ -270,7 +270,7 @@ The default `TargetType` for data flowing into the functions pipeline is an Edge MimeType: "application/text" ``` -If along with this pipeline configuration, you also configured the `Trigger` to be `http` trigger, you could then send any data to the app-service-configurable' s `/api/v2/trigger` endpoint and have it compressed, encrypted and sent to your configured URL above. +If along with this pipeline configuration, you also configured the `Trigger` to be `http` trigger, you could then send any data to the app-service-configurable' s `/api/v3/trigger` endpoint and have it compressed, encrypted and sent to your configured URL above. !!! example "Example - HTTP Trigger configuration" ```yaml diff --git a/docs_src/microservices/application/ApplicationServices.md b/docs_src/microservices/application/ApplicationServices.md index 0de6cdd9ab..06d077dce5 100644 --- a/docs_src/microservices/application/ApplicationServices.md +++ b/docs_src/microservices/application/ApplicationServices.md @@ -33,7 +33,7 @@ See [Built-in Functions](./BuiltIn.md) section for full list of SDK supplied fun !!! Note The App SDK provides much more functionality than just filtering, formatting and exporting. The above simple example is provided to demonstrate how the functions pipeline works. With the ability to write your custom pipeline functions, your custom application services can do what ever your use case demands. -There are three primary triggers that have been included in the SDK that initiate the start of the function pipeline. First is the HTTP Trigger via a POST to the endpoint `/api/v2/trigger` with the EdgeX Event data as the body. Second is the EdgeX MessageBus Trigger with connection details as specified in the configuration and the third it the External MQTT Trigger with connection details as specified in the configuration. See the [Triggers](./Triggers.md) section for full list of available `Triggers` +There are three primary triggers that have been included in the SDK that initiate the start of the function pipeline. First is the HTTP Trigger via a POST to the endpoint `/api/v3/trigger` with the EdgeX Event data as the body. Second is the EdgeX MessageBus Trigger with connection details as specified in the configuration and the third it the External MQTT Trigger with connection details as specified in the configuration. See the [Triggers](./Triggers.md) section for full list of available `Triggers` Finally, data may be sent back to the Trigger response by calling `.SetResponseData()` on the context. If the trigger is HTTP, then it will be an HTTP Response. If the trigger is EdgeX MessageBus, then it will be published to the configured host and publish topic. If the trigger is External MQTT, then it will be published to the configured publish topic. diff --git a/docs_src/microservices/application/Triggers.md b/docs_src/microservices/application/Triggers.md index 49c22acb68..73bad9b7f4 100644 --- a/docs_src/microservices/application/Triggers.md +++ b/docs_src/microservices/application/Triggers.md @@ -152,7 +152,7 @@ Trigger: ## HTTP Trigger -Designating an HTTP trigger will allow the pipeline to be triggered by a RESTful `POST` call to `http://[host]:[port]/api/v2/trigger/`. +Designating an HTTP trigger will allow the pipeline to be triggered by a RESTful `POST` call to `http://[host]:[port]/api/v3/trigger/`. ### Type Configuration @@ -162,7 +162,7 @@ Designating an HTTP trigger will allow the pipeline to be triggered by a RESTful Type: "http" ``` -The `Type=` is set to `http`. This will enable listening to the `api/v2/trigger/` endpoint. No other configuration is required. The Context function `ctx.SetResponseData([]byte outputData)` stores the data to send back as the response to the requestor that originally triggered the HTTP Request. +The `Type=` is set to `http`. This will enable listening to the `api/v3/trigger/` endpoint. No other configuration is required. The Context function `ctx.SetResponseData([]byte outputData)` stores the data to send back as the response to the requestor that originally triggered the HTTP Request. !!! note The HTTP trigger uses the `content-type` from the HTTP Header to determine if the data is JSON or CBOR encoded and the optional `X-Correlation-ID` to set the correlation ID for the request. diff --git a/docs_src/microservices/core/command/Ch-Command.md b/docs_src/microservices/core/command/Ch-Command.md index b8c34c33c2..8be08e4521 100644 --- a/docs_src/microservices/core/command/Ch-Command.md +++ b/docs_src/microservices/core/command/Ch-Command.md @@ -180,7 +180,7 @@ The message topic names act like the HTTP paths and methods in REST requests. Th Below is an example of the `MessageEnvelope` for command query request: ```json { - "ApiVersion": "v2", + "apiVersion": "v3", "RequestId": "e6e8a2f4-eb14-4649-9e2b-175247911369", "CorrelationID": "14a42ea6-c394-41c3-8bcd-a29b9f5e6835", "ContentType": "application/json", @@ -232,7 +232,7 @@ Example of querying device core commands by device name via messaging: 1. Send query request message to external MQTT broker on topic `edgex/commandquery/request/Random-Boolean-Device`: ```json { - "ApiVersion": "v2", + "apiVersion": "v3", "ContentType": "application/json", "CorrelationID": "14a42ea6-c394-41c3-8bcd-a29b9f5e6835", "RequestId": "e6e8a2f4-eb14-4649-9e2b-175247911369" @@ -266,7 +266,7 @@ Base64-decoding the Payload: { "name":"WriteBoolValue", "set":true, - "path":"/api/v2/device/name/Random-Boolean-Device/WriteBoolValue", + "path":"/api/v3/device/name/Random-Boolean-Device/WriteBoolValue", "url":"http://edgex-core-command:59882", "parameters":[ {"resourceName":"Bool", "valueType":"Bool"}, @@ -276,7 +276,7 @@ Base64-decoding the Payload: { "name":"WriteBoolArrayValue", "set":true, - "path":"/api/v2/device/name/Random-Boolean-Device/WriteBoolArrayValue", + "path":"/api/v3/device/name/Random-Boolean-Device/WriteBoolArrayValue", "url":"http://edgex-core-command:59882", "parameters":[ {"resourceName":"BoolArray","valueType":"BoolArray"}, @@ -287,7 +287,7 @@ Base64-decoding the Payload: "name":"Bool", "get":true, "set":true, - "path":"/api/v2/device/name/Random-Boolean-Device/Bool", + "path":"/api/v3/device/name/Random-Boolean-Device/Bool", "url":"http://edgex-core-command:59882", "parameters":[ {"resourceName":"Bool","valueType":"Bool"} @@ -297,7 +297,7 @@ Base64-decoding the Payload: "name":"BoolArray", "get":true, "set":true, - "path":"/api/v2/device/name/Random-Boolean-Device/BoolArray", + "path":"/api/v3/device/name/Random-Boolean-Device/BoolArray", "url":"http://edgex-core-command:59882", "parameters":[ {"resourceName":"BoolArray","valueType":"BoolArray"} @@ -315,7 +315,7 @@ Example of querying all device core commands via messaging: 1. Send query request message to external MQTT broker on topic `edgex/commandquery/request/all`: ```json { - "ApiVersion": "v2", + "apiVersion": "v3", "ContentType": "application/json", "CorrelationID": "14a42ea6-c394-41c3-8bcd-a29b9f5e6835", "RequestId": "e6e8a2f4-eb14-4649-9e2b-175247911369", @@ -358,7 +358,7 @@ Example of making get command request via messaging: 1. Send command request message to external MQTT broker on topic `edgex/command/request/Random-Boolean-Device/Bool/get`: ```json { - "ApiVersion": "v2", + "apiVersion": "v3", "ContentType": "application/json", "CorrelationID": "14a42ea6-c394-41c3-8bcd-a29b9f5e6835", "RequestId": "e6e8a2f4-eb14-4649-9e2b-175247911369", @@ -417,7 +417,7 @@ Example of making put command request via messaging: 1. Send command request message to external MQTT broker on topic `edgex/command/request/Random-Boolean-Device/WriteBoolValue/set`: ```json { - "ApiVersion": "v2", + "apiVersion": "v3", "ContentType": "application/json", "CorrelationID": "14a42ea6-c394-41c3-8bcd-a29b9f5e6835", "RequestId": "e6e8a2f4-eb14-4649-9e2b-175247911369", @@ -453,7 +453,7 @@ The payload is the base64-encoding json struct: ### Configuring for secure MQTT connection In real word, users usually need to provide credentials or certificates to connect to external MQTT broker. -To seed such secrets to Secret Store for Command service, you can follow the instructions from the [Seeding Service Secrets](../../security/SeedServiceSecrets.md) document. +To seed such secrets to Secret Store for Command service, you can follow the instructions from the [Seeding Service Secrets](../../security/SeedingServiceSecrets) document. The following example shows how to set up Command service to connect to external MQTT broker with `usernamepassword` authentication. @@ -540,13 +540,13 @@ regex command name `.rotation` will return event including `Xrotation`, `Yrotati Note that the [RE2 syntax](https://github.com/google/re2/wiki/Syntax) accepted by Go's `regexp` package contains character like `.`, `*`, `+` ...etc. These characters need to be URL-encoded before executing: ```shell -$ curl http://localhost:59882/api/v2/device/name/Simple-Device01/%2Erotation +$ curl http://localhost:59882/api/v3/device/name/Simple-Device01/%2Erotation { - "apiVersion": "v2", + "apiVersion": "v3", "statusCode": 200, "event": { - "apiVersion": "v2", + "apiVersion": "v3", "id": "821f9a5d-e521-4ea7-83f9-f6bce6881dce", "deviceName": "Simple-Device01", "profileName": "Simple-Device", diff --git a/docs_src/microservices/device/Ch-DeviceServices.md b/docs_src/microservices/device/Ch-DeviceServices.md index b2c1fe7936..01540d711f 100644 --- a/docs_src/microservices/device/Ch-DeviceServices.md +++ b/docs_src/microservices/device/Ch-DeviceServices.md @@ -208,7 +208,7 @@ Each Device Service also has detailed configuration to enable connection to it's ##### Secure Mode -When running an Device Service in secure mode, secrets can be stored in the SecretStore by making an HTTP `POST` call to the `/api/v2/secret` API route on the Device Service. The secret data POSTed is stored to the service's secure`SecretStore` . Once a secret is stored, only the service that added the secret will be able to retrieve it. See the [Secret API Reference](../../api/devices/Ch-APIDeviceSDK.md#swagger) for more details and example. +When running an Device Service in secure mode, secrets can be stored in the SecretStore by making an HTTP `POST` call to the `/api/v3/secret` API route on the Device Service. The secret data POSTed is stored to the service's secure`SecretStore` . Once a secret is stored, only the service that added the secret will be able to retrieve it. See the [Secret API Reference](../../api/devices/Ch-APIDeviceSDK.md#swagger) for more details and example. ##### Insecure Mode diff --git a/docs_src/microservices/general/index.md b/docs_src/microservices/general/index.md index a82174bc05..d471554ba6 100644 --- a/docs_src/microservices/general/index.md +++ b/docs_src/microservices/general/index.md @@ -56,7 +56,7 @@ This can be accomplished with a custom application service that sets the functio !!! example "Example - DTO from Core Data in JSON format for the `EventsPersisted` metric as publish to the EdgeX MessageBus" ```json { - "apiVersion": "v2", + "apiVersion": "v3", "name": "EventsPersisted", "fields": [ { diff --git a/docs_src/microservices/support/scheduler/Ch-Scheduler.md b/docs_src/microservices/support/scheduler/Ch-Scheduler.md index d27e5b99f0..6abbfae00a 100644 --- a/docs_src/microservices/support/scheduler/Ch-Scheduler.md +++ b/docs_src/microservices/support/scheduler/Ch-Scheduler.md @@ -142,7 +142,7 @@ Below are only the additional settings and sections that are specific to Support |Port|59880|run the request against the default core data port| |Protocol|http|Make a RESTful request to core data| |Method|DELETE|Make a RESTful delete operation request to core data| - |Path|/api/v2/event/age/604800000000000|request core data's remove old events API with parameter of 7 days | + |Path|/api/v3/event/age/604800000000000|request core data's remove old events API with parameter of 7 days | |Interval|midnight|run the operation every midnight as specified by the configuration defined interval| diff --git a/docs_src/security/Ch-APIGateway.md b/docs_src/security/Ch-APIGateway.md index 2291f55b23..3fff1d0669 100644 --- a/docs_src/security/Ch-APIGateway.md +++ b/docs_src/security/Ch-APIGateway.md @@ -158,9 +158,9 @@ EDGEX_ADD_PROXY_ROUTE: "app-myservice.http://edgex-app-myservice:56789" ``` When a request to the API gateway is received, -such as `GET https://localhost:8443/app-myservice/api/v2/ping`, +such as `GET https://localhost:8443/app-myservice/api/v3/ping`, the API gateway will reissue the request as -`GET http://edgex-app-myservice:56789/api/v2/ping`. +`GET http://edgex-app-myservice:56789/api/v3/ping`. Note that the route prefix is stripped from the re-issued request. @@ -173,7 +173,7 @@ REST API provided by the EdgeX microservices by sending an HTTP request to the service endpoint. E.g., a client can consume the ping endpoint of the Core Data microservice with curl command like this: - curl http://:59880/api/v2/ping + curl http://:59880/api/v3/ping Where `` is the Docker IP address of the container running the core-data microservice (if using Docker), @@ -185,7 +185,7 @@ The API gateway serves as single external endpoint for all the REST APIs. The curl command to ping the endpoint of the same Core Data service, as shown above, needs to change to: - curl https://:8443/core-data/api/v2/ping + curl https://:8443/core-data/api/v3/ping Comparing these two curl commands you may notice several differences. @@ -284,12 +284,12 @@ resources behind the API gateway. Again, without the API Gateway in place, here is the sample request to hit the ping endpoint of the EdgeX Core Data microservice using curl: - curl http://:59880/api/v2/ping + curl http://:59880/api/v3/ping With the security service and JWT authentication is enabled, the command changes to: - curl -k -H 'Authorization: Bearer ' https://myhostname:8443/core-data/api/v2/ping + curl -k -H 'Authorization: Bearer ' https://myhostname:8443/core-data/api/v3/ping In summary the difference between the two commands are listed below: diff --git a/docs_src/security/Ch-RemoteDeviceServices.md b/docs_src/security/Ch-RemoteDeviceServices.md index ef2278b030..e89e73c727 100644 --- a/docs_src/security/Ch-RemoteDeviceServices.md +++ b/docs_src/security/Ch-RemoteDeviceServices.md @@ -384,9 +384,9 @@ The easiest way to test the setup is to make a call from the local machine to the remote `device-virtual` service: ```shell -$ curl -s http://127.0.0.1:59900/api/v2/config | jq +$ curl -s http://127.0.0.1:59900/api/v3/config | jq { - "apiVersion": "v2", + "apiVersion": "v3", "config": { "Writable": { "LogLevel": "INFO", diff --git a/docs_src/walk-through/Ch-WalkthroughCommands.md b/docs_src/walk-through/Ch-WalkthroughCommands.md index 74b6ad2d47..eb72919db7 100644 --- a/docs_src/walk-through/Ch-WalkthroughCommands.md +++ b/docs_src/walk-through/Ch-WalkthroughCommands.md @@ -23,7 +23,7 @@ Use either the Postman or Curl tab below to walkthrough getting the list of comm === "Postman" - Make a GET request to `http://localhost:59882/api/v2/device/name/countcamera1`. + Make a GET request to `http://localhost:59882/api/v3/device/name/countcamera1`. !!! Note Please note the change in port for the command request above. We are no longer calling on core metadata in this part of the walkthrough. The command micro service is at port 59882 by default. @@ -35,7 +35,7 @@ Use either the Postman or Curl tab below to walkthrough getting the list of comm Make a curl GET request as shown below. ``` shell - curl -X GET localhost:59882/api/v2/device/name/countcamera1 | json_pp + curl -X GET localhost:59882/api/v3/device/name/countcamera1 | json_pp ``` !!! Note @@ -59,14 +59,14 @@ Use either the Postman or Curl tab below to walkthrough getting the list of even === "Postman" - Make a GET request to `http://localhost:59880/api/v2/event/count/device/name/countcamera1`. + Make a GET request to `http://localhost:59880/api/v3/event/count/device/name/countcamera1`. === "Curl" Make a curl GET request as shown below. ``` shell - curl -X GET localhost:59880/api/v2/event/count/device/name/countcamera1 + curl -X GET localhost:59880/api/v3/event/count/device/name/countcamera1 ``` The response returned should indicate no events for the camera in core data. @@ -106,7 +106,7 @@ Use either the Postman or Curl tab below to walkthrough actuating the device. === "Postman" - Make a PUT request to `http://localhost:59882/api/v2/device/name/countcamera1/ScanDepth` with the following body. + Make a PUT request to `http://localhost:59882/api/v3/device/name/countcamera1/ScanDepth` with the following body. ``` json {"depth":"9"} @@ -120,7 +120,7 @@ Use either the Postman or Curl tab below to walkthrough actuating the device. Make a curl PUT request as shown below. ``` shell - curl -X PUT -d '{"depth":"9"}' localhost:59882/api/v2/device/name/countcamera1/ScanDepth + curl -X PUT -d '{"depth":"9"}' localhost:59882/api/v3/device/name/countcamera1/ScanDepth ``` !!! Warning @@ -139,7 +139,7 @@ docker logs edgex-core-command The last lines of the log entries should highlight the attempt to contact the non-existent device. ``` -level=ERROR ts=2021-09-16T20:50:09.965368572Z app=core-command source=http.go:47 X-Correlation-ID=49cc97f5-1e84-4a46-9eb5-543ae8bd5284 msg="failed to send a http request -> Put \"camera-device-service:59990/api/v2/device/name/countcamera1/ScanDepth?\": unsupported protocol scheme \"camera-device-service\"" +level=ERROR ts=2021-09-16T20:50:09.965368572Z app=core-command source=http.go:47 X-Correlation-ID=49cc97f5-1e84-4a46-9eb5-543ae8bd5284 msg="failed to send a http request -> Put \"camera-device-service:59990/api/v3/device/name/countcamera1/ScanDepth?\": unsupported protocol scheme \"camera-device-service\"" ... ``` diff --git a/docs_src/walk-through/Ch-WalkthroughDeviceProfile.md b/docs_src/walk-through/Ch-WalkthroughDeviceProfile.md index 1c009f96ce..8e824a9087 100644 --- a/docs_src/walk-through/Ch-WalkthroughDeviceProfile.md +++ b/docs_src/walk-through/Ch-WalkthroughDeviceProfile.md @@ -114,7 +114,7 @@ Click on the link below to download and save the device profile (YAML) to your s === "Postman" - Make a POST request to `http://localhost:59881/api/v2/deviceprofile/uploadfile`. The request should not include any additional headers (leave the defaults). In the Body, make sure "form-data" is selected and set the Key to `file` and then select the device profile file where you saved it (as shown below). + Make a POST request to `http://localhost:59881/api/v3/deviceprofile/uploadfile`. The request should not include any additional headers (leave the defaults). In the Body, make sure "form-data" is selected and set the Key to `file` and then select the device profile file where you saved it (as shown below). ![image](EdgeX_WalkthroughPostmanFile.png) @@ -127,7 +127,7 @@ Click on the link below to download and save the device profile (YAML) to your s Make a curl POST request as shown below. ``` shell - curl -X POST -F 'file=@/path/to/your/profile/here/EdgeX_CameraMonitorProfile.yml' http://localhost:59881/api/v2/deviceprofile/uploadfile + curl -X POST -F 'file=@/path/to/your/profile/here/EdgeX_CameraMonitorProfile.yml' http://localhost:59881/api/v3/deviceprofile/uploadfile ``` If your API call is successful, you will get a generated id for your new `DeviceProfile` in the response area. @@ -138,6 +138,6 @@ Click on the link below to download and save the device profile (YAML) to your s Note that the file location in the curl command above needs to be replaced with your actual file location path. Also, if you do not save the device profile file to `EdgeX_CameraMonitorProfile.yml`, then you will need to replace the file name as well. #### Test the GET API -If you make a GET call to the `http://localhost:59881/api/v2/deviceprofile/all` URL (with Postman or curl) you will get a listing (in JSON) of all the device profiles (and all of its associated `deviceResource` and `deviceCommand`) currently defined in your instance of EdgeX, including the one you just added. +If you make a GET call to the `http://localhost:59881/api/v3/deviceprofile/all` URL (with Postman or curl) you will get a listing (in JSON) of all the device profiles (and all of its associated `deviceResource` and `deviceCommand`) currently defined in your instance of EdgeX, including the one you just added. [](Ch-WalkthroughDeviceService.md){: .md-button } diff --git a/docs_src/walk-through/Ch-WalkthroughDeviceService.md b/docs_src/walk-through/Ch-WalkthroughDeviceService.md index e5bf59806f..54d0b627ea 100644 --- a/docs_src/walk-through/Ch-WalkthroughDeviceService.md +++ b/docs_src/walk-through/Ch-WalkthroughDeviceService.md @@ -33,11 +33,11 @@ Use either the Postman or Curl tab below to walkthrough creating the `DeviceServ === "Postman" - Make a POST request to `http://localhost:59881/api/v2/deviceservice` with the following body: + Make a POST request to `http://localhost:59881/api/v3/deviceservice` with the following body: ``` json { - "apiVersion": "v2", + "apiVersion": "v3", "service": { "name": "camera-control-device-service", "description": "Manage human and dog counting cameras", @@ -59,14 +59,14 @@ Use either the Postman or Curl tab below to walkthrough creating the `DeviceServ ``` shell - curl -X 'POST' 'http://localhost:59881/api/v2/deviceservice' -d '[{"apiVersion": "v2","service": {"name": "camera-control-device-service","description": "Manage human and dog counting cameras", "adminState": "UNLOCKED", "labels": ["camera","counter"], "baseAddress": "camera-device-service:59990"}}]' + curl -X 'POST' 'http://localhost:59881/api/v3/deviceservice' -d '[{"apiVersion": "v3","service": {"name": "camera-control-device-service","description": "Manage human and dog counting cameras", "adminState": "UNLOCKED", "labels": ["camera","counter"], "baseAddress": "camera-device-service:59990"}}]' ``` If your API call is successful, you will get a generated ID for your new `DeviceService`. #### Test the GET API -If you make a GET call to the `http://localhost:59881/api/v2/deviceservice/all` URL (with Postman or curl) you will get a listing (in JSON) of all the device services currently defined +If you make a GET call to the `http://localhost:59881/api/v3/deviceservice/all` URL (with Postman or curl) you will get a listing (in JSON) of all the device services currently defined in your instance of EdgeX, including the one you just added. [](Ch-WalkthroughProvision.md){: .md-button } diff --git a/docs_src/walk-through/Ch-WalkthroughProvision.md b/docs_src/walk-through/Ch-WalkthroughProvision.md index 34c580a5f6..dccd04fae2 100644 --- a/docs_src/walk-through/Ch-WalkthroughProvision.md +++ b/docs_src/walk-through/Ch-WalkthroughProvision.md @@ -30,12 +30,12 @@ Use either the Postman or Curl tab below to walkthrough creating the `Device`. === "Postman" - Make a POST request to `http://localhost:59881/api/v2/device` with the following body: + Make a POST request to `http://localhost:59881/api/v3/device` with the following body: ``` json [ { - "apiVersion": "v2", + "apiVersion": "v3", "device": { "name": "countcamera1", "description": "human and dog counting camera #1", @@ -69,7 +69,7 @@ Use either the Postman or Curl tab below to walkthrough creating the `Device`. Make a curl POST request as shown below. ``` shell - curl -X 'POST' 'http://localhost:59881/api/v2/device' -d '[{"apiVersion": "v2", "device": {"name": "countcamera1","description": "human and dog counting camera #1","adminState": "UNLOCKED","operatingState": "UP","labels": ["camera","counter"],"location": "{lat:45.45,long:47.80}","serviceName": "camera-control-device-service","profileName": "camera-monitor-profile","protocols": {"camera-protocol": {"camera-address": "localhost","port": "1234","unitID": "1"}}}}]' + curl -X 'POST' 'http://localhost:59881/api/v3/device' -d '[{"apiVersion": "v3", "device": {"name": "countcamera1","description": "human and dog counting camera #1","adminState": "UNLOCKED","operatingState": "UP","labels": ["camera","counter"],"location": "{lat:45.45,long:47.80}","serviceName": "camera-control-device-service","profileName": "camera-monitor-profile","protocols": {"camera-protocol": {"camera-address": "localhost","port": "1234","unitID": "1"}}}}]' ``` If your API call is successful, you will get a generated ID (a UUID) for your new `Device`. @@ -79,13 +79,13 @@ Use either the Postman or Curl tab below to walkthrough creating the `Device`. #### Test the GET API -Ensure the monitor camera is among the devices known to core metadata. If you make a GET call to the `http://localhost:59881/api/v2/device/all` URL (with Postman or curl) you will get a listing (in JSON) of all the devices currently defined in your instance of EdgeX that should include the one you just added. +Ensure the monitor camera is among the devices known to core metadata. If you make a GET call to the `http://localhost:59881/api/v3/device/all` URL (with Postman or curl) you will get a listing (in JSON) of all the devices currently defined in your instance of EdgeX that should include the one you just added. There are many [additional APIs on core metadata](../../api/core/Ch-APICoreMetadata) to retrieve a `DeviceProfile`, `Device`, `DeviceService`, etc. As an example, here is one to find all devices associated to a given `DeviceProfile`. ``` shell -curl -X GET http://localhost:59881/api/v2/device/profile/name/camera-monitor-profile | json_pp +curl -X GET http://localhost:59881/api/v3/device/profile/name/camera-monitor-profile | json_pp ``` [](Ch-WalkthroughCommands.md){: .md-button } diff --git a/docs_src/walk-through/Ch-WalkthroughReading.md b/docs_src/walk-through/Ch-WalkthroughReading.md index ab3064dd6c..5dae10a492 100644 --- a/docs_src/walk-through/Ch-WalkthroughReading.md +++ b/docs_src/walk-through/Ch-WalkthroughReading.md @@ -31,13 +31,13 @@ Use either the Postman or Curl tab below to walkthrough sending an `Event` with === "Postman" - Make a POST request to `http://localhost:59880/api/v2/event/camera-monitor-profile/countcamera1/HumanCount with the body below. + Make a POST request to `http://localhost:59880/api/v3/event/camera-monitor-profile/countcamera1/HumanCount with the body below. ``` json { - "apiVersion": "v2", + "apiVersion": "v3", "event": { - "apiVersion": "v2", + "apiVersion": "v3", "deviceName": "countcamera1", "profileName": "camera-monitor-profile", "sourceName": "HumanCount", @@ -79,7 +79,7 @@ Use either the Postman or Curl tab below to walkthrough sending an `Event` with Make a curl POST request as shown below. ``` shell - curl -X POST -d '{"apiVersion": "v2","event": {"apiVersion": "v2","deviceName": "countcamera1","profileName": "camera-monitor-profile","sourceName": "HumanCount","id":"d5471d59-2810-419a-8744-18eb8fa03464","origin": 1602168089665565200,"readings": [{"id": "7003cacc-0e00-4676-977c-4e58b9612abc","origin": 1602168089665565200,"deviceName": "countcamera1","resourceName": "HumanCount","profileName": "camera-monitor-profile","valueType": "Int16","value": "5"},{"id": "7003cacc-0e00-4676-977c-4e58b9612abf","origin":1602168089665565200,"deviceName": "countcamera1","resourceName": "CanineCount","profileName": "camera-monitor-profile","valueType": "Int16","value": "3"}]}}' localhost:59880/api/v2/event/camera-monitor-profile/countcamera1/HumanCount + curl -X POST -d '{"apiVersion": "v3","event": {"apiVersion": "v3","deviceName": "countcamera1","profileName": "camera-monitor-profile","sourceName": "HumanCount","id":"d5471d59-2810-419a-8744-18eb8fa03464","origin": 1602168089665565200,"readings": [{"id": "7003cacc-0e00-4676-977c-4e58b9612abc","origin": 1602168089665565200,"deviceName": "countcamera1","resourceName": "HumanCount","profileName": "camera-monitor-profile","valueType": "Int16","value": "5"},{"id": "7003cacc-0e00-4676-977c-4e58b9612abf","origin":1602168089665565200,"deviceName": "countcamera1","resourceName": "CanineCount","profileName": "camera-monitor-profile","valueType": "Int16","value": "3"}]}}' localhost:59880/api/v3/event/camera-monitor-profile/countcamera1/HumanCount ``` ![image](EdgeX_WalkthroughSendEvent_Curl.png) @@ -118,23 +118,23 @@ Use either the Postman or Curl tab below to walkthrough getting the list of even === "Postman" - Make a GET request to retrieve the `Event`s associated to the `countcamera1` device: `http://localhost:59880/api/v2/event/device/name/countcamera1`. + Make a GET request to retrieve the `Event`s associated to the `countcamera1` device: `http://localhost:59880/api/v3/event/device/name/countcamera1`. - Make a GET request to retrieve the `Reading`s associated to the `countcamera1` device: `http://localhost:59880/api/v2/reading/device/name/countcamera1`. + Make a GET request to retrieve the `Reading`s associated to the `countcamera1` device: `http://localhost:59880/api/v3/reading/device/name/countcamera1`. === "Curl" Make a curl GET requests to retrieve 10 of the last `Event`s associated to the `countcamera1` device and to retrieve 10 of the human count readings associated to `countcamera1` ``` shell - curl -X GET localhost:59880/api/v2/event/device/name/countcamera1 | json_pp - curl -X GET localhost:59880/api/v2/reading/device/name/countcamera1 | json_pp + curl -X GET localhost:59880/api/v3/event/device/name/countcamera1 | json_pp + curl -X GET localhost:59880/api/v3/reading/device/name/countcamera1 | json_pp ``` There are [many additional APIs on core data](../../api/core/Ch-APICoreData) to retrieve `Event` and `Reading` data. As an example, here is one to find all events inside of a start and end time range. ``` shel -curl -X GET localhost:59880/api/v2/event/start/1602168089665560000/end/1602168089665570000 | json_pp +curl -X GET localhost:59880/api/v3/event/start/1602168089665560000/end/1602168089665570000 | json_pp ``` [](Ch-WalkthroughExporting.md){: .md-button } diff --git a/docs_src/walk-through/EdgeX_WalkthroughGetValueDescriptors.png b/docs_src/walk-through/EdgeX_WalkthroughGetValueDescriptors.png deleted file mode 100644 index 4d805dda29..0000000000 Binary files a/docs_src/walk-through/EdgeX_WalkthroughGetValueDescriptors.png and /dev/null differ