Concepts and Fundamentals

At its core, the Frame.io API is a way to communicate to Frame.io's servers from a device or App, and therefore every call is going to involve networking, or having multiple computers talking to each other!

The hardest part of any relationship is good communication, and the server / client relationship is no different. How many times a day do you have to ask someone to repeat themselves, or mishear someone in a way that leads to confusion? The same thing happens when two computers talk to each other.

Not only do we have to deal with normal communication issues, but we also have to make sure that other computers can't hear what we are talking about, and computers can't just talk quietly. Frame.io requires that all data be encrypted when communicating with our servers, which adds another layer of complexity.

When implementing the C2C API you will almost certainly be using a third-party library to take care of netwokring implementation details for you, but the networking stack often causes the majority of real-world errors, so having a basic understanding of what's going on when you make a call to Frame.io's servers is a good idea. Here is a brief glossary of terms we should be familiar with:

TCP/IP: - Transmission Control Protocol / Internet Protocol

TCP/IP is the collection of different components or layers that are standardized across the world to enable the transfer of data from location to location. Rather than rewrite our own explanation, we recommend taking a look at this high level, easy to read resource.

TLS/SSL: Transport Layer Security / Secure Socket Layer

TLS/SSL are often used interchangeably. While they are not the exact same thing, nowadays they can be used synonymously. TLS is the successor to SSL, but the acronym has persisted.

Cryptography and Encryption, the study and application of how to communicate without others listening in, and is one of the deepest rabbit holes in computer science. Luckily, there are only a few concept a C2C integrator needs to understand when implementing: public keys, private keys, and certificates.

For a deeper dive on TLS, see this overview.

Public and Private Keys: A public key is like a lock. A private key is like a key to that lock.

Let’s imagine I write a message down on a piece of paper and want to mail it to my friend. But I also want to make sure that no one can read it until it's delivered.

The first thing I do is ask my friend to send me a lock that only they have the key to.

When I receive the lock, I put my secret message in a box use the lock to secure it. The lock is public; anyone who sees the box can see the lock, but because they do not have the key to the lock (which is privately held by my friend), they cannot peek inside. For anyone besides my friend who wished to read the message, the lock is useless. In fact, I lack the key, so not even I can unlock it now.

But when my friend receives the locked box, they simply unlock it with the key they have been keeping sage this whole time.

Public and private keys operate exactly the same. You can send a public key to anyone. They encrypt a message with it. Only the holder of the private key can decrypted that message. As long as the private key is kept secret, the public key is useless for decoding messages it creates.

Public and private keys are the basis for how TLS works, and how two parties can communicate publicly while working out a way to keep their messages unreadable to anyone trying to listen in.

Certificates: Certificates contain public and private keys, and are signed by a trusted third party.

When a Certificate Authority signs a key, it's stamps that key with a message saying this key is from the person it says it's from. Anyone who gets a public key — for Google, say — can check that it was stamped by one of these trusted third-parties. If it is not, we assume it was issued y. a bad actor pretending to be someone else and throw an error.

Frame.io’s certificates are signed by the Amazon Root CA 1 certificate authority. These certificates are available via various resources such as the Certifi library (which itself is used by Mozilla and the Python Requests library).

Here is a link to the Certifi github repo and certificate PEM bundle which we recommend using to validate HTTPS requests to api.frame.io.

Server: A server is a computer that serves information to (or stores information from) other computers. When you go to Frame.io in your Web Browser, the browser asks Frame.io's server what it should display and our server sends back our webpage. Every time you click a button or take an action in Frame.io, the web browser tells our server what you want to do, our server does it, and then tells your Web Browser what happened. When you upload a piece of footage to Frame.io, you are sending it to our servers!

Client: A client is an application that is asking the server for information or sending new information for it to store. When implementing the C2C API, you will be building a C2C client.

HTTP/S: Hypertext Transfer Protocol / Secure

HTTP/S is a protocol used in the application layer for the TCP/IP model. The only difference in HTTP vs HTTPS is the security. HTTPS implements TLS/SSL verification into the network request.

There are different versions of HTTP. As the protocol has evolved, new standards have been set. Version 1.1 is still the standard across the globe and should be used for communication with the Frame.io API. For more information see the HTTP Requests section below.

RESTful API: REST stands for REpresentational State Transfer, and is a design philospphy for crafting API's based on HTTP requests and responses.

REST is commonly used as shorthand to describe the general approach of using HTTP to allow one program to interact with another -- as opposed to using it to supply webpages to a browser -- even if the API doesn't faithfully implement REST principles.

JSON: JavaScript Object Notation.

A Format for sending data between computers. Although it was originally created to represent JavaScript objects, the format has since been adopted as a ubiquitous standard for networked communication. The C2C API responds to requests with JSON data.

Amazon Web Services (AWS): AWS is a service for building web applications in the Cloud! At Frame.io we use AWS to store our media. When uploading media, you will interact directly with AWS's Simple Storage Service to hand your data to Frame.io

AWS S3: Amazon's Simple Storage Service is a way to store data in the cloud. S3 is where Frame.io stores its video and audio media, and where integrations will upload their data to.