Accessing Forge storage from a remote via REST API

You can configure a remote back end to store data on Forge’s Key-Value Store (KVS) or Custom Entity Store via REST API.

Prerequisites

In order to communicate with Forge’s back end via REST API from remote, you’ll need to configure your app to call a remote backend (from a Custom UI or UI Kit 2 frontend). To do this, you’ll need to configure the following properties in your manifest.yml file:

Additional prerequisites for Custom Entities

Before you can start storing data in the Custom Entity Store, you’ll need to define your entities first. See Custom Entity Store and Custom entities for detailed information on how to do this.

Authentication

The REST API only accepts OAuth bearer tokens as authentication. Your app must supply this token in the Authorization: Bearer {bearerToken} header of the request.

Requests

All requests should be sent in JSON format to the base URL https://api.atlassian.com/forge/storage/kvs, followed by the desired operation defined in the API. The following Node.js example uses the fetch function from the node-fetch module to request data from the REST API:

1
2
'use strict'
import fetch from 'node-fetch';
const apiBaseUrl = 'https://api.atlassian.com/forge/storage/kvs';
export async function fetchFromStorage(token, apiBaseUrl) {
  const headers = {
     'Accept': 'application/json',
     'Authorization': `Bearer ${token}`,
     'Content-Type': 'application/json'
  }
  return await fetch(`${apiBaseUrl}/v1/get`, { method: "POST", headers });
}

Quotas and limits

Forge hosted storage capabilities are subject to limits, usage, and syntax constraints. These include limits to the number of operations, key lengths, and object depth. Any request that exceeds a quota or limit will return a 429 status with an error code of RATE_LIMIT_EXCEEDED.

See Storage quotas and Storage limits for details about relevant constraints.

Error handling

In conjunction with proper HTTP status codes, non-2xx responses will have the following schema:

1
2
{
  code: string; // "INVALID_KEY_FORMAT"
  message: string; // "Invalid key format"
}

Each 400 Bad Request response will be accompanied by an error code containing more information. The following tables lists all possible error codes, what they mean, and what you can do to address each one:

Key-related errors

Value-related errors

Entity-related errors

Query-related errors