Getting ready to use the Figma API
It's high time to get to know the Figma API, one of the real stars of our show.
This is the first time in this course we'll dip our toes into what the Figma API looks like and how it works. In this lesson, we will:
See what Figma offers in ways of documentation and API playground
Set up an API client to help us use the Figma API
Create our own API token
Learn how we know our unique document ID
Understand the document structure
Learn what we can only do in paid plans
We'll start by scanning the documentation Figma provides and seeing how their API playground works.
The Figma API in short#
The API is read-oriented, so you can't currently write to (i.e., change) documents, comments, files, or anything else.
There is a rate limit on the API, so you should avoid using it excessively.
To call Figma's API, you will need to pass along your token and then specify what you are requesting. The coarsest item we are interested in would be a file, else known as a document. How about we inspect a brand-new, blank Figma design file?
Finding the document ID#
Let's pop into Figma and create a new file. I will rename mine "My test file."
One of the least intuitive things in Figma is actually finding the document ID itself. We can do this by right-clicking the window tab near the top (with our document name) and clicking Copy Link.
Paste this somewhere so we can take a look at it. Mine looks like this:
The sections are—
Some of these are self-explanatory. It's worth mentioning that the main type you will use is files, but there are several more, like teams and components. Further, Figma has the concept of nodes, a node essentially denoting an object in your file. The
viewport is so we can—just like you have probably done in Google Maps at some point or another—share a location so that others can directly see what you want them to look at.
We will talk more about document structure soon. For now, copy the part between
/My-test-file—that is the document ID segment we need to use with the API now.
Checking the API docs/explorer#
The page is not exactly short, and you'll navigate the fastest if you use the left-hand side menu. As always, documentation like this is something you want to bookmark if you are building things with, or for, an API.
You can skip quite a lot of the sections in the beginning. For now, what we want to do is just get a quick glimpse of how stuff looks under the hook. In fact, what we want to do is to scroll all the way down to
Figma files > Endpoints > GET file.
Trying the API explorer#
There's a handy API playground here, under the heading Try it out for yourself. Only one piece of data is required, and that is the file ID we just got. Paste it in there. Normally you need a token to use the API—the playground allows you to create a temporary one by just clicking the Get personal access token button. Do so now. After a second or so, you should have that field pre-populated with the temporary token. Click Submit API request. Admittedly, the box with the response is tiny, but if you scroll through the response, it's as real as it gets.
You can try out the other endpoints Figma provides here just as easily. There is no magic wand, so your response depends entirely on what resource you point it to. A blank document won't give much back!
It's about time we get our own token and put things in order!
Get your own API token#
Open up Figma. Click the Figma icon in the upper left corner. Click
Help and account > Account settings. Scroll almost all the way down until you see Personal access tokens.
Add a token description and press enter/return. You'll be presented a token, which will have a format like
83715-e8346292-bf3v-88s1-n932-j364ge9h687e. Copy it. Keep this token a secret, and don't check this into your code! If you do happen to leak it, just revoke the old one and get a new token.
Notice also how you can see whether a token has been used or not, and how you can also revoke access to individual tokens here. We won't do so in this course, but it's really something you want to keep in the back of your head as you continue working with Figma under more production-like circumstances.
Don't worry about my on-screen token: It'll be revoked by the time you see this.
What is reserved for Pro plans and admins#
In case you would be interested in creating webhooks, these need to be created by organization admins. Effectively, that rules out free users. There does not appear to be any other differences in what is available through the API in regards to what your plan allows.