ARTIK Cloud is designed to be as easy as possible to integrate with existing devices and services. This article presents the basic concepts behind how ARTIK Cloud recognizes 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 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 by applications and devices in a message. ARTIK Cloud recognizes two message types; one carries only data, and the other carries Actions for devices.
Each message in ARTIK Cloud 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 can automatically infer the user ID and application ID from the access token that was generated during authentication. When the message is received, ARTIK Cloud also creates a timestamp.
Applications must specify at least one of these parameters when querying ARTIK Cloud. 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 and assigned on user creation, which is done through Samsung 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 is called a device. Devices in ARTIK Cloud 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. Every device in ARTIK Cloud is identified with a unique device ID. Device IDs are assigned by ARTIK Cloud 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. 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. 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 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 is designed to be agnostic of the data sent by devices and applications. To make this data usable, ARTIK Cloud requires 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, the Manifest takes a string as input that corresponds to the data, and outputs a list of normalized fields/values that ARTIK Cloud can store.
When querying data stored in ARTIK Cloud, 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 is also accurate. Manifests cannot be updated or deleted, but new ones can be uploaded to ARTIK Cloud. Learn more about the Manifest.
An Action is a specific type of ARTIK Cloud 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 ARTIK Cloud Rules that send Actions to devices when triggered by incoming messages. Rules are one of the most powerful ARTIK Cloud features, 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.
ARTIK Cloud tools
These web-based tools allow ARTIK Cloud developers, users and researchers to view and manage key information. 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.