API Reference

This is a full documenation on the API of the MODE cloud platform.

Version
2.1
Base URL
https://api.tinkermode.com

Introduction

The MODE API is an HTTP-based API that allows hardware devices, mobile apps and external servers to interact wth the MODE cloud in a straighforward manner. It is a RESTful API, with a few exceptions where non-RESTful access is more suitable.

All API requests should be made securely via HTTPS. For prototyping with devices that are not capable of making HTTPS connections, the API is also available via unencrypted HTTP. You are highly discouraged from using unsecure access for your production system.

Request Headers

Content Type and Content Length

If an API request contains a request body, it must also contain Content-Type and Content-Length headers. Depending on the API resource/endpoint, the request body is expected to be either in JSON (application/json) or as a web form (application/x-www-form-urlencoded).

Authorization

Some resources/endpoints have methods that can only be accessed by certain authorized clients. To access these restricted methods, the client must provide an Authorization request header, which should be in the following format:

Authorization: ModeCloud <AUTH_CODE>

where <AUTH_CODE> is an authentication token.

How the authentication token can be obtained depends on the nature of the API client, as explained below.

Client Authentication

Requests to the MODE API is usually made by one of the following entities: a user (by way of a mobile or web app), a device, or an authorized external program/service. An API client can identify itself by using the Authorization request header, which contains an authentication token.

Here are the ways to obtain this token:

For Users

The token is obtained through requests to the Authentication endpoints. Depending on project settings, user authentication may involve round-trip verification by an SMS message, direct password input, or special server-to-server API calls.

For Devices

The token is the API Key assigned to a device instance when it was provisioned. If the device was pre-provisioned, you can retrieve this key from the Developer Console. If you are using On-demand Device Provisioning, this key is returned in the API call that adds a device to a home.

For Other Clients

You can provision Project API Keys for use by external programs or services that integrate with the MODE platform.

For example, you may have a scheduler service that sends commands to your devices periodically. Or, if you have your own user account system, your server will need to make backend API calls to MODE during user registration and login.

For these API clients, you can provision Project API Keys in your project's Settings screen on the Developer Console. You can also control what additional permissions a Project Key can have besides basic API access.

WebSocket Endpoints

Some of the API endpoints are intended for clients to establish WebSocket connections. They do not behave like regular RESTful API resources. These include:

  • WebSocket endpoint that allows a user to listen to events happening at her home(s).
  • WebSocket endpoint that allows a device to listen to commands sent by users or authorized client programs.

Resources

Here are the API resources/endpoints available to clients:

Users

Registered end-users of a project.

Homes

A "home" represents a container of devices and is owned/managed by one or more users.

Devices

Cloud-aware devices that have been registered to a home. Some devices connect to the cloud directly, while some are under the control of a hub.

Authentication

For handling API client authentication. These resources do not adhere strictly to a RESTful model.

Device Registration

For initiating the process to register devices to homes. This step is required unless the project was configured to allow On-Demand Device Provisioning.

User Session

This resource becomes available after a user has successfully authenticated with the API service.