Introduction

Using ohyay's API — a way of interacting through code such as JavaScript — opens up a lot of possibilities, like integrating with other services + software 🤝 and programming more complex things.

ohyay exposes two application programming interfaces (APIs).

• The frontend API can be used to manipulate workspaces, rooms and elements. This is an extensive API that can used to extend the functionality of ohyay and integrate with other services.

• The backend API can be used to manage workspaces. This can be especially useful if you need to manage a large number of workspaces.

Accessing the frontend API

The frontend API is called from inside a workspace using JavaScript code in an iframe element.

To write code that calls the API you must first create an iframe element and enable the Allow API Access property on it. The iframe will send a message to the JavaScript console which lists all the main calls. You can also find a full TypeScript declaration file at https://ohyay.co/ohyay.d.ts.

In the API-enabled iframe element, edit the Asset URL property to choose an existing script or create a new script which will provide the code for the iframe. The Create Script File button will create a template which includes stubs for two of the most common places in which you might make API calls:

• In the API-loaded listener, you can make calls that run once the API is loaded.

• In the message handler, you can act in response to messages posted to the iframe element. These messages can be sent to an iframe by invoking a Post Message in an action. Any parameter passed will be received in the iframe's message handler.

There are also additional handlers that can be used to handle events such as when the iframe is rendered.

Editing JavaScript code in an iframe

You will typically go through many iterations of editing and testing code in an iframe. Each time you wish to edit and update your code, you should follow these steps:

• Click on the Asset URL property in the iframe to launch asset library dialog that shows all JavaScript files.
• Click on the edit link for the script you wish to edit.
• Make changes in the editor and then click Save and then Close to close the editor.
• In the asset library dialog that should still be open, click on the (already selected) script. This will update the iframe with the new code.

Accessing the backend API

As a REST API, the backend API can be accessed through a variety of languages including JavaScript and Python. Although you call the backend API from outside of a workspace, access is still tied to your ohyay account.

Before you can use the API, you need to create an API token, which can be done from https://ohyay.co/ohyay_api.html.

Sending a request to the backend API

Requests can be sent over HTTPS POST to the endpoint that corresponds to the operation you want to perform. The body of the request contains a JSON web token signed with your API key. The payload of the web token should contain the parameters for the request.

Example: JavaScript

The jsonwebtoken package can be used to generate the token needed for the request. Start by installing this package.

npm install --save jsonwebtoken

Once you've installed the library, you can generate requests like so

import * as jwt from 'jsonwebtoken';

// Create the request. Each request must contain your user id.
// You can get your user id from https://ohyay.co/ohyay_api.html
const req = { userId: <User ID> };
const apiKey = <your api key>;
const token = jwt.sign(req, apiKey)
fetch('https://us-central1-ohyay-prod-d7acf.cloudfunctions.net/ohyayapi/list-workspaces', {
  method: 'POST',
  headers: {
    'Content-Type': 'text/plain'
  },
  body: token,
});

Example: Python

JSON web tokens can be generated in python using the pyjwt package.

pip install pyjwt

import jwt

# This example uses the requests package for HTTP requests
# It can be installed with `pip install requests`
import requests

token = jwt.encode({
  "userId": "<user id>",
}, "<api key>", algorithm="HS256")

res = requests.post(
  "https://us-central1-ohyay-prod-d7acf.cloudfunctions.net/ohyayapi/list-workspaces",
  data=token,
  headers={ "content-type": "text/plain" },
)

print(res.text) # Contains response json