ARTIK cloud services are designed to be as easy as possible to integrate with existing IoT devices and services. This article presents the basic concepts behind how ARTIK cloud services recognize users, devices, data and applications.
The API's authorization model is based on a very simple set of permissions (READ and WRITE) on users and other entities in the system. These grant a user the right to perform activities in ARTIK cloud services via the API calls.
If a user has created her own account, only she will have access to her data. If you have admin privileges on the user, you will be able to perform some limited actions on behalf of the user, such as getting the user's profile information and changing the user's application properties.
Future changes to the API might include more fine-grained management of permissions by the user, more permission types and more activity checks. Learn more about authorization.
Data is stored in ARTIK cloud services by applications and devices in a message. ARTIK cloud services recognize two message types; one carries only data, and the other carries Actions for devices.
Each message in ARTIK cloud services is associated with a set of identifying metadata: the device ID, user ID and application ID. To record a message, an application must provide the payload and the device ID. ARTIK cloud services can automatically infer the user ID and application ID from the access token that was generated during authentication. When the message is received, a timestamp is also created.
Applications must specify at least one of these parameters when querying ARTIK cloud services. This means that depending on the scenario, data can be queried per user, per device or per application. Learn about sending and receiving messages via REST and WebSockets.
A user ID is defined by ARTIK cloud services and assigned on user creation, which is done through ARTIK Cloud Accounts. With a user ID, applications may obtain the user's profile and device list, and may request to create and manage an application profile for that user.
Users can additionally choose to grant an application access to their data. Once an application has been granted access, it may also request data from the user's devices. Users may remove these permissions at any time.
Device ID and device type
Any source of data in ARTIK cloud services is called a device. Devices in ARTIK cloud services can be sensors, appliances, applications, services, etc. Usually one user will own one or more devices, and devices can send messages or be used to send messages into ARTIK cloud services. Every device in ARTIK cloud services is identified with a unique device ID. Device IDs are assigned by ARTIK cloud services when devices are first created in the system. A device ID is a unique instance of a device type.
A device type defines a category of device in ARTIK cloud services. For example, "Samsung Galaxy Gear Fit" is a device type, and "Andrea's Samsung Galaxy Gear Fit" will have a unique device ID. Only the owner, vendor or OEM of a device will likely need to create a device type. Owners of a device type are responsible for keeping the name and description of a device type updated. Learn more about creating devices.
Each application is assigned a unique ID by ARTIK cloud services. An application ID is required to obtain an OAuth2 access token and to request data from an application, provided that the user has granted access. Developers can request as many application IDs as needed. If you have multiple application IDs, data can be shared among your applications if users have authorized this. Learn how to find your application ID.
Raw and normalized data
Data collected by ARTIK cloud services is called raw data: it refers to the original format and structure, unmodified by the system. After collection, raw data is processed and becomes normalized data: JSON-formatted, with standardized field names and values.
ARTIK cloud services are designed to be agnostic of the data sent by devices and applications. To make this data usable, ARTIK cloud services require what we call a Manifest. The Manifest, which is associated with a device type, describes the structure of the data. When an application or device sends a message to ARTIK cloud services, the Manifest takes a string as input that corresponds to the data, and outputs a list of normalized fields/values that ARTIK cloud services can store.
When querying data stored in ARTIK cloud services, developers can request either the original "raw" format or the standard normalized format. This is the output generated when passing the original message through the Manifest. Accurately defining and updating the Manifest will ensure that the normalized data delivered by ARTIK cloud services is also accurate. Manifests cannot be updated or deleted, but new ones can be uploaded to ARTIK cloud services. Learn more about the Manifest.
An Action is a specific type of message that sends a command to a device. Examples include turning a device on or off, setting text, and changing a color value. Actions are defined in the Manifest and are intended to be sent and executed in near real-time, so we recommend that you connect your destination devices via WebSockets. Learn how to define Actions for device types in our web portal and directly in the Manifest.
You can define Rules that send Actions to devices when triggered by incoming messages. Rules are one of the most powerful features of ARTIK cloud services, allowing you to quickly create an IoT ecosystem with smart device interactions that work outside silos. Learn how to define Rules in our web portal and programmatically.
These web-based tools allow developers, users and researchers to view and manage key information on ARTIK cloud services. The Developer Dashboard provides a convenient interface for you to create and manage device types and applications. And the API Console lets you execute API calls and see the results straight from your browser.