Overview
Whether the end goal is publishing, editing, or simply pushing Assets into Frame.io for review, the first step to the majority of useful OAuth App integrations with Frame.io will involve listing out a userâs context, and ultimately, a directory view.
The basic hierarchy of a Frame.io account context goes like so:
- Account
- Team
- Project
- Assets
- Project
- Team
Accordingly, thatâs the hierarchy weâll be building out with sequential API calls. And then once weâre inside a project, weâll list out folders, and inside of them, Assets and Version Stacks.
Thereâs only one potential wrinkle before we get started:
Shared projects
One of the key user roles in Frame.io is the Collaborator â a User with Project access who may or may not belong to that Projectâs owning organization.
Leaving aside the permissions / allowed actions side of the conversation, the key difference between a Team Member and a Collaborator is that a Collaboratorâs membership is strictly to a Project, and not necessarily to a Team. This presents a small wrinkle for directory listings.
While the basic hierarchy above (Account > Team > Project > Assets) should work for the majority of use cases, it wonât include the list of Projects on which an authenticated user is a Collaborator, but not a Team Member.
To steer around this when listing directories, you can either:
- Fetch a Userâs shared projects, unpack the Team and Account hierarchy, and zip it all together, or
- Fetch a Userâs shared projects, and list them all together as a separate context.
Either method is fine; the latter is a bit easier, but the former is closer to how Frame.io's web app presents similar information. In any case, the methods covered in this guide apply to both.
Note: single user context
This guide assumes youâre working within the context of a single userâs permissions â either your own via token, or a logged in userâs via OAuth grant.
Building out the directory structure
1) Fetch the userâs accounts
GET https://api.frame.io/v2/accounts
To get a Userâs Accounts, make the above call with a valid bearer token. In response, youâll get a list of every Account on which the user has Team Member or Team Manager access to at least one Team. You may also receive Teams for which a user has billing/Admin rights, but no Team access, but this is rare, and will be washed out in the next step.
While the full payload for a Frame.io Account is fairly verbose, the most important pieces of information youâll want to grab for each Account are:
id
display_name
owner
email
name
- (optionally)
image
Of the above non-id
fields, only owner.email
is required, so that batch will give you enough context to apply a bit of conditional logic for presenting Accounts. Our recommendation is to check, and if not null, display the Account with the following order of preference:
- "
display_name
" - "
owner.name
's Account" - "
owner.email
's Account"
Once your user chooses an Account, you can fetch the Teams.
Account Images are temporary URLs
Note: the Accountâs image returned by our API will be a pre-signed S3 key, so the URL returned will âdieâ after about a day. To work around this, you should either re-fetch the image every time your service loads, or ideally, store it locally.
2) Fetch the Accountâs Teams
GET https://api.frame.io/v2/accounts/{{account_id}}/teams
Teams in Frame.io may be âpublicâ (discoverable to any Team Member in the Account), or âprivateâ (discoverable only to specific Team Members). The good news is, the Frame.io API will handle all of that, so all you need to do, given an account_id
, is make the above call with a valid bearer token.
In response, youâll receive a list of Teams.
Don't forget to paginate
While itâs unlikely that a user will be on more than a few Accounts, Teams are a resource that can scale pretty quickly. While the Frame.io API's default limits are fairly high, it's always good to check response headers, and if necessary, paginate.
You can find more info on pagination by reading Pagination and Errors.
From each Team, grab the following attributes:
id
name
- (optionally)
team_image
Now, when a Team is selected, youâll want to get all its constituent Projects.
Note: if you wish, you may also GET https://api.frame.io/v2/teams
for a user, and our API will return every Team a user belongs to, regardless of Account context. While this will technically work, it runs the risk of looking a little messy unless you:
- Reestablish context by reflecting the Account name next to each Team
- Ideally, allow your user to search the text of the list
If you're going to list out shared Projects from the Account level down, this is when you'll want to start that ball rolling by calling GET https://api.frame.io/v2/projects/shared
. Each Project response in that list will have the following attributes, which you can carry forward as your build your directory:
id
(of the Project itself)team_id
team.account_id
Alternatively, this is where you can make an affordance for "Shared Projects" simply by adding it as a "Team" on any chosen Account context. If you do choose to do that, it's helpful to the end user if you visually separate Shared Projects from true Team-scoped Projects, as the single Shared Projects list may include many different true Account and Team contexts under the hood.
3) Fetch the Teamâs Projects
GET https://api.frame.io/v2/teams/{{team_id}}/projects
Now that youâre in a Team, the next step is to make the above call (with a valid bearer token), and fetch all the Projects within the Team.
For each Project, youâll want to grab:
id
name
root_asset_id
- (optionally)
private
, in case you want to differentiate for the user in your UI
The root_asset_id
is an important piece of Frame.ioâs resource architecture: itâs essentially a dummy Asset that stands in for the root of a Project, and enables you to easily recurse through a folder structure.
And that is exactly what weâre going to do next!
Listing folders and assets
To quickly recap â if weâve gotten this far, it means weâve established the combined context of:
- Account
- Team
- Team Projects (and root_asset_ids)
- Shared Projects (and root_asset_ids)
And thatâs all we need to create or fetch an Asset.
4) Build the initial folder structure
GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder
This will list out all the folders in a project, starting from the root_asset_id
. If there are no folders, youâll get back an empty list. If you want to include both files and folders (e.g. if your next step would be to GET
an Asset from Frame.io, simply omit the query string parameter.
The other two filter options available for the type parameter are file and version_stack. All three filters are mutually exclusive, and an unfiltered call will return all three types mixed together.
5) Dig through the directory tree
For each folder that comes back, youâll need to capture:
id
name
As each folder is an Asset, your workflow for drilling through a folder structure will look like this:
GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder
- Render out the folder names in a list
- When a user clicks on a folder pass the folderâs id into the following query:
GET https://api.frame.io/v2/assets/{{folder_id}}/children?type=folder
6) Create and upload
Into a folder:
POST https://api.frame.io/v2/{{folder_id}}/children
Once you have the id of the folder youâd like to upload into, simply make a POST
to its children, per the resource documentation and guide. This will create a placeholder Asset, and (depending on the method you choose), return:
- An
id
that you can use for tracking - (If youâre loading a local file) a list of one or more upload_urls that you can use to PUT your file directly to Frame.io's S3 bucket.
Thatâs it! Youâre done!
Into a Version Stack:
Version Stacks present a similar workflow, with one added step covered in this guide, summarized below. The keys are remembering that a Version Stack is a container that looks like an Asset, but behaves like a folder; and that you have to upload your Asset first, and then stack it into your Version Stack as separate actions.
Accordingly, if you want to upload an Asset into a Version Stack, youâll need:
- The Version Stackâs
id
- The Version Stackâs
parent_id
(e.g. its containing folder or Project root)
First, POST https://api.frame.io/v2/assets/{{parent_id}}/children
to create your new Asset. Capture the new id
in your response.
Now, you can use your new Assetâs id and POST https://api.frame.io/v2/assets/{{version_stack_id}}/version
, with a body payload of:
{
"next_asset_id": "<new-asset-id>"
}```
And youâre done!
Updated 9 months ago