Understanding core concepts
The C2C API builds on a number of core technologies that are important to understand before undertaking an integration. Take a glance at the headings of this article. If some of these terms are new to you, that's great! It's why we put this guide together. Take a look and feel free to reach out to our team for additional resources if you get stuck on any particular concept. We are here to help!
What you need to know
To integrate with the C2C API, it's important that you understand the basics of how to do the following:
- Networking basics like working with TLS / SSL, TCP / IP, etc.
- Making HTTPS requests.
- Authentication and Authorization patterns.
Networking basics and glossary
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.
HTTP/S requests
You've probably seen HTTP before: at the head of almost every website you've interacted with! HTTP stands for Hyper Text Transfer Protocol, and is way for computers to talk to each other.
You can think of HTTP like a set of standard forms that must be filled out for a client to make requests of the server and for the server to respond to those requests -- the same way you might fill our a government form to request information or apply for programs. The government won't understand your request or bother to respond to it unless you've filled out the proper forms!
HTTP requests are the way you take every action with the Frame.io application. If the C2C API is a library, the types of HTTP requests you can make are its individual functions.
You can get a great overview of how HTTP works in this blogpost, and it's important that you understand the basics before moving forward. If this is your first time working with HTTP request, maybe look up a quick introductory tutorial before moving forward. To set yourself up for success, make sure you have a cursory understanding of the following HTTP concepts:
-
URLs
- Protocol
- Host
- Port
- Resource
- Headers
- Content-Type/Mimetype
- Request and Response Payloads
- How HTTP verbs are used: GET, POST, PUT, DELETE, etc.
- Form Data
In most cases, your networking library should build your request for you, but in case that is not an option here is the RFC (https://greenbytes.de/tech/webdav/rfc2616.html) for HTTP/1.1.
Authentication and authorization
We'll go over these concepts in more detail later, but it's important we understand these two concepts at a high level.
Authentication: When a user is authenticated, it means that we have determined a request is coming from the person it says it is coming from. When you sign into a website with a username/password you are authenticating yourself by proving that you know your password. Two factor authentication methods -- like getting a text with a code from your bank that you have to enter before being allowed to log in -- is also a form of authentication.
Authorization: When a user is authorized, that means that they are confirmed to have permissions to take some action. When you add a collaborator to a Frame.io project or a Google doc, you are authorizing them to see that project or doc. Frame.io / Google have already authenticated that the user is who they say they are, so that you can feel comfortable authorizing them to take an action.
OAuth: Short for Open Authorization and is a standard framework for handling Authorization by integrating with a third-party for Authentication.
Scopes: Scopes are the actions a user is authorized to take. When connecting a device to frame.io, you will request / be granted certain scopes that authorize you to take certain actions. For instance, the asset_create scope allows you to create and upload assets. You can think of scopes as being another word for permissions.
Next Up
If you haven’t already, we encourage you to reach out to our team, then continue to the next guide. We look forward to hearing from you!
