A fully typed client for the Figma REST API, with quality-of-life features.
A fully typed client for the Figma REST API, with quality-of-life features. Used by figmarine as an API client.
- Always up-to-date: generated from Figma's OpenAPI spec and updated by a CI script
- JavaScript client with a fully typed API
- Development mode that automatically caches GET responses, with persistence across runs
- Built-in rate limiting to protect you from an IP ban
- Easy authentication
Install the package with the following command:
pnpm i @figmarine/restTo use the client, import the package, create a client and call its methods. All methods are asynchronous and return an Axios response object.
import { Client, WebhookV2Event } from '@figmarine/rest';
const c = await Client({ mode: 'development' });
// The v1 API contains most methods for manipulating Figma data.
const response = await c.v1.getTeamProjects('1234567890');
// The v2 API contains Webhooks.
await c.v2.postWebhook({
event_type: WebhookV2Event.PING,
description: 'This is my custom webhook!',
team_id: '1234567890',
endpoint: 'https://myserver.com/endpoint',
passcode: 'mySecretPasscode',
});The Client function exposes the following options.
Defines whether your client is being developed or running in a production environment. At the moment, only used to handle the default behaviour of the built-in cache. May be used to control default logging verbosity in the future.
An OAuth2 token to authenticate to the client. It is mandatory to either pass this token or a personalAccessToken.
A Personal Access Token to authenticate to the client. It is mandatory to either pass this token or an oauthToken.
See Built-in Cache.
See Rate Limiting.
The following environment variables are supported:
-
NODE_ENV: used to initialise the run mode todevelopmentorproduction -
FIGMA_PERSONAL_ACCESS_TOKEN: used to authenticate with a Personal Access Token -
FIGMA_OAUTH_TOKEN: used to authenticate with an OAuth 2.0 Token
Figma applies a rate limit to the number of API requests you can send, to prevent spam. The rate limiting algorithm is complex and cannot be properly emulated by API clients, so the Figmarine REST client uses two approaches.
Exponential auto-retry: When the API returns a 429 Too Many Requests error, the client waits for however long the API requested, and then automatically retries sending the request. The client at least waits one minute on the initial error, and then waits exponentially longer (two minutes, then four, etc.) on subsequent errors that happen immediately after.
Proactive rate limiting: The client sends at most 10 requests per minute when that option is active based on anecdotal information about the limits enforced by Figma. This option is not recommended if you don't have other clients frequently querying the API.
You may choose the behaviour to use with the rateLimit option:
| Value | Behaviour |
|---|---|
'reactive' |
only does auto-retry [default] |
'proactive' |
does both auto-retry and proactive rate limiting |
true |
does both auto-retry and proactive rate limiting |
false |
does nothing |
This client ships with a disk cache that's enabled by default in development mode and disabled by default in production mode. The cache is stored to disk and restored across runs to allow you to quickly write and test Node.js scripts as you would typically develop them prior to running them in a CI.
[!CAUTION] Changes made through the Figma application or other API clients cause the cache to become stale. The cache is intended to speed up development rather than to be used in production. It is your responsibility to decide if stale cache is acceptable for your use cases.
const c = await Client({ mode: 'development' });
// Takes 1 second on the first run, instantaneous on the second run.
await c.v1.getFile('gcW09NWmIPr158bu49ieX8');You may force-enable the disk cache by passing true to the cache option, or by passing any configuration object. All options are optional.
const c = await Client({ cache: { ttl: 6000 } });You may force-disable it by passing false.
const c = await Client({ cache: false });Controls wether the cache content clears automatically when the client knows it may be invalid.
| Value | Behaviour |
|---|---|
true |
the whole cache gets cleared whenever a POST, PUT or DELETE request is made [default]
|
false |
the cache never self-clears and you have to do it yourself |
Controls where on the disk the cache is written.
| Value | Behaviour |
|---|---|
undefined |
written to your operating system's temporary folder [default] |
| relative path | written to a subfolder in the temporary folder |
| absolute path | written to the provided path |
Number of seconds for which a request response will be kept in the cache.
| Value | Behaviour |
|---|---|
undefined |
purged after approximately 1 year [default] |
| number | purged after that number of seconds |
You can access the cache instance by using the cacheInstance property, and you can loop over its content to inspect it.
for await (const [key] of c.cacheInstance.iterator()) {
console.log(key);
}[!NOTE] The instance is not designed to be used for arbitrary data, and it is strongly typed for use with Axios data. If you'd like to extend its capabilities, contributions are welcome!
c.cacheInstance.clear();[!TIP] If you use the cache and make edits to the file you're developing on, remember to clear the cache on the next run after editing the file.
Clone the project
git clone https://github.com/Sidnioulz/figmarine.gitGo to the project directory
cd packages/restInstall dependencies
pnpm installBuild the code as you make changes
pnpm devCheck that tests run as you make changes
pnpm test:devSee how to contribute.
Distributed under the MIT License.
Please open a conversation in the discussion space to ask a question.
Please open an issue for bug reports or code suggestions.
- @figma/rest-api-spec provides the up-to-date OpenAPI Spec file used by this package
- swagger-typescript-api is the codegen engine used by this package