Identificadores: Key vs. Id

Key como parámetro de ruta

Una key es un identificador que permite identificar entidades como Devices o Variables. Una key de una entidad se define en la ruta como <entity_key>, por ejemplo, <device_key>. Las keys permiten identificar la instancia de una entidad con su correspondiente id o label. La identificación con el label debe utilizar el prefijo ~.

// Petición GET para obtener un Device específico

// Definición de la URL
https://api.netux.com/api/v2.0/devices/<device_key>/

// Identificación usando el Id del Device
https://api.netux.com/api/v2.0/devices/4f169cc906d07d65aa7a/

// Identificación usando el Label del Device
https://api.netux.com/api/v2.0/devices/~first-device/

Id como parámetro de ruta

Un id es un identificador que permite identificar entidades como Devices o Variables. Un id de una entidad se define en la ruta como <entity_id>, por ejemplo <log_id>. Los ids permiten identificar la instancia de una entidad sólo por su id.

// Petición GET para obtener un Log Event específico

// Definición de la URL
https://api.netux.com/api/v2.0/events/<event_key>/logs/<log_id>/

// Identificación usando el Id del Log
https://api.netux.com/api/v2.0/events/<event_key>/logs/6d07d65aa7a4f169cc90/

Key como parámetro de cuerpo

Algunas peticiones POST tienen un parámetro de entidad. Un buen ejemplo es la petición Crear Evento. Esta petición tiene como parámetro una organization. Por lo tanto, para esta petición, el parámetro de la organization puede ser enviado de cualquiera de las siguientes maneras:

// Petición POST para crear un Evento
curl -X POST 'https://api.netux.com/api/v2.0/events/' \
 -H 'Content-Type: application/json' \
 -H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73' \
 -d '{
 
// 1. Enviando la Organization usando el Id
"organization":"567890ff1d8472686e9abb4f"

// 2. Enviando la Organization usando el Label
"organization":"~first-organization"

// 3. Enviando la Organization como un Object
"organization":{"id":"567890ff1d8472686e9abb4f"}

}'

Es simple, todos los parámetros de entidad son keys en el cuerpo de la petición, por lo tanto pueden ser identificados con su id pero también como object o con su label.