Using Custom REST API Calls
👩🏽‍💻

Using Custom REST API Calls

Created
May 21, 2023 2:57 PM
Tags

API Call Action

Using the API Call action you can make a call to most any API that supports the following options:

  • GET/POST/PUT/DELETE methods
  • Unauthenticated or authenticated with an HTTP header or API key somewhere in the URL or HTTP Body.

You can use this to transmit data to 3rd party APIs or even call the Frame API itself. There are several variables that you can include in the API call data as well. Some of the variables contain personal user information, so users are first prompted for consent before that data is transmitted.

Usage

Example

Here is a sample API call that uses the Frame API.

image
  • URL: https://api.framevr.io/automate/v1/frames/yourframe1234/assets/images/%apiKey%
  • Method: POST
  • API Key: Frame API Key
  • POST/PUT Body:
  • {
        "assetName": "someCat",
        "settings": {
            "position": {
                "x": 1,
                "y": 1,
                "z": 1
            },
            "imageURL": "<https://imgur.com/JX9H0Ki.png>"
        }
    }
    

This will create an image of a cat at (1, 1, 1) in yourframe1234.

Note

The interactivity editor will auto-expand parameters sections on objects it sees as having invalid data.

Authentication

Authentication is optional, but there are multiple ways this can be supplied.

Keys

The API key transmitted with the request should be chosen from the list. If you have a Frame API key, this will appear in the list. If you don't have one yet, go to your Profile to generate one.

The keys here are supplied from a list at the bottom of your Profile. Enter them here:

image

Header

Some APIs use an HTTP header for authentication. To use this feature, enter the header name in "HTTP Header Name". Commonly it is "X-API-Key".

Other

If the API Key must be entered somewhere else, the variable %apiKey% can be inserted into the URL or the POST/PUT Body.

Data

URL

A valid url must be specified, including the http:// or https:// portion. Variables (see below) can be used in this field to assist with transmitting data and even authentication (FRAME API expects the API Key in the URL).

Method

The following HTTP methods are supported:

  • GET
  • POST
  • PUT
  • DELETE

The API call will be made with the chosen HTTP method.

POST and PUT require a body.

POST/PUT Body (JSON)

For POST/PUT requests, a body is required. Most APIs use JSON, so the request will be sent with Content-Type: application/json and Accept: application/json HTTP headers set. This requires the body to be valid JSON.

Variables are supported in this field. See below.

The JSON can be nicely formatted with extra spaces, but within each value the data must not contain line breaks and tabs. These must be must be escaped - that is, represented with a special code (example: \n, \t).

There are online tools that can assist in formatting JSON.

Variables

Variables are available to transmit a variety of useful data.

To use a variable, just type it (including the % signs) into the field. For example: https://api.sample.com/get?apiKey=%apiKey%

Non-sensitive variables

The following variables can be used in the URL or the POST/PUT Body:

  • %uniqueUserId% - Unique user ID. If not logged in, this is "Anonymous".
  • %apiKey% - the API key selected below.
  • %frameName% - this FRAME's name.
  • %assetId% - a unique ID of the asset that triggered this action.
  • %assetName% - the name of the asset that triggered this action.
  • %assetType% - the type of the asset that triggered this action.

Sensitive variables

The following sensitive variables can be used in the URL or the POST/PUT Body.

  • %email% - The user's email address.
  • %nametag% - The user's nametag.

User Consent

If these are used, the user will be asked before transmitting this data, but only once. They will be presented with the following popup the first time an API Call action is triggered:

image

The user can change this later in Profile -> User Preferences.

image

Users that are not logged in, guests, are considered to not be granting consent, so an API call containing sensitive variables will not be called for them.