obniz Cloud API

The obniz cloud API is an API for manipulating devices tied to an account, serverless events, etc. You can use it for yourself or other users by creating a WebApp and getting approval from the user. Currently, the following information can be manipulated

  • WebApp itself
  • WebApp installation information
  • User information for approved users
  • Device owned by the authorized user
  • Serverless events for approved users

GraphQL API

The obniz cloud API employs GraphQL. The endpoint is below

https://api.obniz.com/v1/graphql

You can get the results by giving a token and query to the endpoint.

const graphQLClient = new GraphQLClient(`https://api.obniz.com/v1/graphql`, {
  headers: {
    authorization: `Bearer ${token}`,
  },
});
const query = `{
  user {
    id,
    name,
    email
  }
}`;
const user = await graphQLClient.request(query);

Document

https://api.obniz.com/v1/graphql

in your browser, you can open the API demo screen along with the documentation.
To use the API, you need to add a token to the header, so it cannot be used in the online demo screen.

It is convenient to make use of the GraphQL application for the desktop that can give a token to a request header for actual use.

Altair
Apollo

Token

In order to use the API and access user information, you must create a WebApp and have the user approve the WebApp. A token will be issued upon approval. Also, there are two types of tokens: those issued per user, and those for the WebApp itself.

  • WebApp token: A token for the WebApp itself. You can get the installation information.
  • OAuth token: A token for each user that is obtained when the user approves. Information tied to the user can be manipulated.

WebApp is required to obtain each. Please see the WebApp for more information.

A token is given in the request header when tapping the GraphQL API.

authorization: Bearer oauth_xxxxxxx

Sample code

There is a sample code on GitHub that uses the API.

Using OAuth to manipulate user and device information
https://github.com/obniz/obniz-webapp-example-oauth

How to use installation to obtain user-installed application information and develop web services
https://github.com/obniz/obniz-webapp-example-install

Install

In IoT development, there are scenes where the same program is used across multiple devices, and each device runs with different settings. With obniz's WebApp, users not only approve and issue access tokens, but they can also "install" multiple WebApps with their settings.

The user installation process is as follows.

  1. The server system runs on AWS and other cloud services and is registered as a WebApp on the obniz cloud.
  2. Users approve WebApps
  3. User installs a WebApp
    During installation, the user is asked about the settings provided in the WebApp and they are saved during the installation.
    Also, if a Webhook URL is set in the WebApp, a webhook will be issued upon installation.
  4. WebApp calls the obniz cloud API to retrieve all installed WebApps.
    Execute the program based on the installation information in the WebApp, and in some cases, auto-scale out.
  5. Synchronize the WebApp with the user's configuration via a webhook issued at each user installation event (creating/updating/deleting an installation) or a periodic fetch

To learn more about installing the WebApp, please see below.

WebApp/Install