This section explains the difference between <keys>
and <ids>
.
Key as Path Parameter
A key is an identifier that allows to identify entities such as Devices
or Variables
. Entity Key parameters in the path are defined as <entity_key>
, e.g. <device_key>
. Entity Keys allow to identify the entity instance with their corresponding id
or label
. The label identification should use the prefix ~
.
Example:
//GET Request to Obtain a Specific Device
//URL Definition
https://industrial.api.ubidots.com/api/v2.0/devices/<device_key>/
//Identification using Device Id
https://industrial.api.ubidots.com/api/v2.0/devices/4f169cc906d07d65aa7a/
//Identification using Device Label
https://industrial.api.ubidots.com/api/v2.0/devices/~first-device/
Id as Path Parameter
An id is an identifier that allows to identify entities such as Devices
or Variables
. Entity Id parameters in the path are defined as <entity_id>
, e.g. <log_id>
. Entity Ids allow to identify the entity instance only by their id
.
Example:
//GET Request to Obtain a Specific Event Log
//URL Definition
https://industrial.api.ubidots.com/api/v2.0/events/<event_key>/logs/<log_id>/
//Identification using Log Id
https://industrial.api.ubidots.com/api/v2.0/events/<event_key>/logs/6d07d65aa7a4f169cc90/
Key as Body Parameter
Certain POST requests have an entity parameter. A good example is the request Create Event. This request has organization
as organization_key parameter. Hence when creating an event the organization parameter can be sent in any of the following ways:
//POST Request to Create an Event
curl -X POST 'https://industrial.api.ubidots.com/api/v2.0/events/' \
-H 'Content-Type: application/json' \
-H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73' \
-d '{
//Sending Organization using the Id
"organization":"567890ff1d8472686e9abb4f"
//Sending Organization using the Label
"organization":"~first-organization"
//Sending Organization as Object
"organization":{"id":"567890ff1d8472686e9abb4f"}
}'
Id as Body Parameter
It's simple, all entity parameters in the body are Keys
, hence they can be identified with their id but also as object or with their label.