Identifiers - Key vs. Id

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.