Introduction
Before we begin making requests, we need to go over some foundational architecture for C2C integrations. (Next article you will be in the terminal, we promise! For now, eat your proverbial vegetables).
The simplified data model for your integration will look something like this:
┌───────────────────┐ ┌─────────┐
│ Project Device 01 │ -> │ Project │
┌───────────┐ ┌──────────────┐ └───────────────────┘ └─────────┘
│ Oauth App │ -> │ Device Model │ ──────────⭥`
└───────────┘ └──────────────┘ ┌───────────────────┐ ┌─────────┐
│ Project Device 02 │ -> │ Project │
└───────────────────┘ └─────────┘Oauth Apps
Your integration will be defined by an Oauth App, an entity registered with our backend that will allow your devices to authorize themselves with Frame.io using Oauth 2. Your Oauth App defines the authorization strategy for your entire integration. Every device your users connect to Frame.io will authorize through the same Oauth App (though integrators with more than one line of device may want one Oauth App for each).
There are three types of Oauth Applications in the Frame.io ecosystem, which we will go over in more detail below. Two of the types are specific to C2C, allowing access to the C2C specific API. If you are not a Camera to Cloud integrator, you will want to avoid C2C documentation.
For C2C partners, which type of Oauth App you wish to use will be determined by the needs of your physical (or virtual) device.
C2C Hardware Devices
The C2C Hardware Devices API is designed to service physical hardware with limited UI capabilities. These devices allow a User to connect them to Frame.io by displaying a 6-digit code, which the user then inputs to the Frame.io website using their own browser.
Hardware devices are issued a client_secret that must be supplied to our backend to receive a 6-digit authorization code.
C2C Applications
The C2C Application API is designed for Applications that want to connect to Frame.io as if they were a piece of hardware. Many applications will not need to do more in Frame.io than supply media, so integrating as a C2C Application may be a good choice for those use cases! When being connected by a user, C2C Applications will be expected to redirect to Frame.io in a browser, then in their own UI, list available accounts and projects for a user to select from. This is a good choice for integrations running on a consumer device, be it desktop or mobile.
C2C Applications are issued a client_id that must be supplied when redirecting the user to our Auth portal.
Why not the general API?
You may be asking yourself why would I choose to integrate as a C2C Application, rather than using Frame.io’s general-purpose REST API? This option is best suited for integrations that:
- Tailor built authentication for a seamless user experience.
- Want access to some C2C-specific features, like device management and the
onlinestatus. - Do not want the overhead of designing and displaying frame.io files and folder structure
Device Models
The device model configures how your device behaves when interacting with the C2C backend, including which features it supports. The following settings are configured by your device model:
- Asset Type: The category of asset your device produces. May be "video", "audio", or "data". Note that "video" includes video files that are muxed with audio.
- Path Name: The name of your integration as it should appear in any uploaded asset's path.
- Tokenized Filepath: C2C only allows uploading assets to specific root filepaths, but below that requirement your device can be configured to upload assets to a dynamically calculated filepath based on the asset's supplied metadata.
- Required Metadata Attributes: What metadata will be required when you upload am asset to Frame.io, most notably to support the tokenized file path.
- Socket Status Enabled: Whether the integration will use low-latency sockets for communicating it's current status, or lower-latency REST calls.
The features your device supports can change across firmware versions. To enable backwards compatibility and a clean user experience — the configuration for you device is dynamically selected based on the detected firmware version. In the near future, an integration will be able to have more than one DeviceModel. Which Device model is used will be determined by comparing the firmware version of the device to the minimum firmware version requirement of a specific device model (see below).
Project Devices and identification
For Hardware Device integrations, the ProjectDevice represents each physical instance of a piece of hardware. For C2C Applications, the ProjectDevice represents each individual installation of the application.
In both cases, a ProjectDevice will identify itself using a unique identification value. client_id or hardware devices, and device_id for C2C Applications. This value should be something guaranteed not to be shared between two devices. It can be the serial number of a device or a random string that the device generated once and saves. The device_id should NOT be a value your device or application does not own, like the MAC address of a computer.
Our backend keeps track of each project device and saves some information about it, such as its current firmware version.
Each ProjectDevice will have a specific Frame.io Project associated with it and an OauthAuthorization granting the device access to the project and a set of scopes detailing what a device is allowed to do. For more on what scopes are available, see the detailed guides on implementing authentication and authorization.
The ProjectDevice is what gets returned by the /me endpoint. A Device can only be actively linked to a single ProjectDevice at a time, and therefore to a single Project at a time.
Firmware Versions
Your device can supply its current firmware version with the x-client-version HTTP header whenever you call an endpoint at https://api.frame.io. Later API guides will include this header in each example. While C2C Applications may not have traditional firmware, they will still be required to supply their software version.
In some instances, our backend must sort multiple firmware versions, and to support this, we require that values MUST be a valid semantic version. These include values like 0.1.2, 2.1.3-preview.01, and 2.1.3-preview.01+build_19770504.01, among others.
An error will be returned if firmware version values are not valid semantic versions. We are aware that not all integrations will track their firmware using semantic versioning, and in such cases, we ask that you keep track of a semantic version to supply our backend for each internal version you create.
By supplying the header, different releases of your firmware or application can support different (and sometimes conflicting) features within Frame.io.
The firmware version is only handled by calls to https://api.frame.io, when making calls to https://applications.frame.io, the header has no effect.
The x-client-version is a required HTTP header, and will be enforced by Frame’s servers in the near future.