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);

GraphQL communication is done using the HTTPS protocol.
Therefore, even if you cannot use a GraphQL client, you can handle it as you would a normal HTTP request.
For details, please refer to here.

About GraphQL

GraphQL is a query language that allows you to retrieve only the data you need, similar to the SELECT statement in SQL.

There are two types of GraphQL API, Query and Mutation, and they can be handled as follows.

• Query ≒ SELECT statement
• Mutation ≒ UPDATE statement

For details, please refer to here.

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

SDK

TypeScript/JavaScript SDK for using GraphQL endpoint is available.
https://github.com/obniz/obniz-cloud-sdk

Since it is type-defined, you can use IDE completion and TypeScript type checking.

Please refer to README for usage.

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 App 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

Error code list