In this age of integrations, sharing data between systems is more important than ever.
Imagine an ecommerce website without integrations. On top of handling product listings, your site would need to build tools for processing payment, shipping, email automation, user accounts, and other functions all by itself. This isn’t a scalable solution — it’s more efficient to outsource these tasks to other services.
So, in order to work together, software applications use application programming interfaces, or APIs. APIs provide a standardized way for two applications to send data back and forth. Your ecommerce site can interact with payment software, shipping software, and any other necessary integrations through their respective APIs.
There are many approaches to building an API, but if you’re interested in introducing software integrations to your product, there’s one special method you should know: REST APIs. In this guide, I’ll explain what a REST API is and why they’re so useful.
To understand REST, we need to review some key terms first:
A client is the person or program using the API. The client makes requests to the API in order to retrieve some information or change something within the application. Your web browser is a client — it interacts with APIs different websites to get page content from them. The requested info is sent back to your browser and displayed on your screen.
A resource is any piece of information that the API can provide the client. For instance, a resource in Facebook’s API could be a user, a page, a photo, or a post. Each resource has a unique name, called the resource identifier.
A server is used by the application that receives client requests, and contains resources that the client wants. The server has an API to interact with clients without giving them direct access to content stored in its database.
Now for our definition. REST is a set of guidelines that software can use to communicate over the internet in order to make integrations simple and scalable. A REST API (also called a “RESTful” API) is a specific type of API that follows these guidelines.
REST stands for Representational State Transfer. This means that when a client requests a resource using a REST API, the server transfers back the current state of the resource in a standardized representation.
In other words, REST APIs work by fielding requests for a resource and returning all relevant information about the resource, translated into a format that clients can easily interpret (this format is determined by the API receiving requests). Clients can also modify items on the server and even add new items to the server through a REST API.
Let’s say I want to build a program that integrates with YouTube. My program (the client) can ask YouTube’s REST API for information about a specific video (a resource). YouTube’s API will respond to my request with the resource state, which includes attributes like the video name, publishing date, and view count, and video link, all packaged in a format that my program can quickly parse and use. My program could also post a video (i.e., add a new resource) to my personal YouTube channel through the API.
Now that we know the benefits of REST APIs, let’s go into detail about what makes REST APIs different from other types of APIs.
The Six Rules of REST APIs
To fully benefit from the functionality that REST provides, APIs must follow six requirements. (Well, technically five are required and one is optional.) Each requirement lays the groundwork for a fast and versatile API.
1. Client-Server Separation
Under REST architecture, the client and server can only interact in one way: The client sends a request to the server, then the server sends a response back to the client. Servers cannot make requests and clients cannot respond — all interactions are initiated by the client.
By simplifying communication between clients and servers, RESTful APIs keep the two conveniently independent. This way, client software can grow their builds without worrying about affecting any other servers, and server contents can be modified without inadvertently affecting clients.
2. Uniform Interface
This guideline states that all requests and all responses must follow a common protocol, or a way of formatting their messages. Applications and servers are written in all sorts of different languages that don’t do a great job of working together without an intermediary. A uniform interface is a common language for any client to communicate with any REST API.
Without standardized communication, translating requests and responses between software would be a total mess. Minor discrepancies would cause information to be jumbled and lost, and applications would have to update their request processes whenever APIs updated theirs. A uniform interface eliminates this possibility.
For most REST APIs, this common language is HTTP, or Hyper-Text Transfer Protocol. HTTP wasn’t created specifically for REST. Rather, REST adopted this communication protocol as the standard for applications that use it.
To use HTTP with a REST API, the client sends a request in a specific format that might look familiar to you. For example, a request to the YouTube API for video data looks like this:
Like all requests to a REST API, this request contains two pieces of information:
GET is the HTTP method. This specifies the action the client wants to make on the resource. There four basic HTTP requests a client can make are:
GET: To retrieve a resource.
POST: To create a new resource.
PUT: To edit or update an existing resource.
DELETE: To delete a resource.
https://… is the URL. The URL contains the uniform resource identifier, or URI, which specifies the target resource.
In this case, the URL is also called an endpoint because it is the location where the API actually interacts with the client.
All calls with a REST API must be stateless. This means that every interaction is independent, and each request and response provides all the information required to complete the interaction. Every request by the client is interpreted by the server as a brand new ask — the server remembers nothing about past requests.
Stateless transfers greatly reduce the amount of server memory needed and improve the odds of a successful response, since the server is not required to take additional action to retrieve old data. This ensures that these interactions are scalable: As software grows and makes more requests, developers don’t need to worry about significantly more memory being used, or overloading the server with requests.
4. Layered System
So far I’ve described API requests as a simple interaction between a client and server, but this is a bit of a simplification. In reality, there are typically more servers between these two entities. These servers, or layers, are there to add security, handle and distribute traffic, or assist with a number of other important functions.
This principle requires that messages between the client and target server should always be formatted and processed the same way, regardless of layers that sit between them. Additional layers should not affect client-server interactions.
When developers follow this guideline, server systems can be rearranged, updated, or otherwise modified with no effect on the core request-response.
Caching occurs when media is stored on a client’s device when visiting a website. When a client returns to that site, the cached data is loaded quickly from local storage instead of being fetched again from the server. Caching saves server resources and bandwidth while decreasing page load time, which is why most large websites do it.
REST APIs are created with data caching in mind. When a server sends its response to a client, the response should indicate whether the resource provided can be cached, and for how long.
6. Code on Demand (Optional)
The final REST principle is optional. If desired, an API can send computer code to clients in its response. This empowers the client to run the code in its own backend.
As long as an API adheres to this set of rules, it is considered RESTful. However, these rules leave plenty of room for developers to customize the functionality of their API. This flexibility distinguishes REST APIs from another common web API method, the Simple Object Access Protocol (SOAP).
REST API vs. SOAP API
REST is usually compared to SOAP, another way to build applications that work over HTTP. The main difference between REST and SOAP is that REST is a set of guidelines, and SOAP is a protocol. REST allows for building APIs with any method, including HTTP, URLs, and JSON. SOAP only uses XML for sending data.
REST is considered a simpler, more efficient alternative to SOAP because it requires writing less code to complete tasks and follows a less rigid structure and logic than SOAP. Additionally, REST sets guardrails for API design, but leaves many choices up to the developer building the API.
Why use REST APIs?
The REST framework was introduced by computer scientist Roy Fielding in 2000, and today it shapes how we view, modify, and transfer content online. Many of the most popular web and cloud companies use REST APIs for their applications, including Facebook, YouTube, Twitter, and Google.
But why REST? Basically, it’s an excellent system for web apps. Here are the main benefits to this type of API:
REST APIs are flexible. They can handle many types of requests and send data in many different formats.
REST APIs are scalable. They are designed for communication between any two pieces of software, regardless of size or capability. As a web application grows and adds more resources, its REST API will be able to quickly handle the increasing amount and variety of requests.
REST APIs incorporate existing web technologies, making them relatively easy to build and use. To request a resource via a REST API, you just need to provide its URL.
How to Use a REST API
Web applications with publicly available APIs will have documentation available on the “developers” section of their websites. Here you’ll find instructions on how to access and use the API in conjunction with your own software. If the API is built with REST principles, the documentation will probably indicate this.
Many APIs require an API key to use. An API key is a unique string of characters that an API provider gives to a developer to authorize access to their API. API keys are often sent with client requests to identify the client to the server. Keep your API key(s) private. If your key falls into the wrong hands, it could be used to do some not-so-good things seemingly on your behalf.
To test out a public API, use a tool that can structure HTTP requests, like Postman. Try a variety of different HTTP methods and URLs, and see what happens.
REST API Examples
You can find REST APIs all over the web — you’ve likely used some today without realizing it. Here are a few examples:
The Twitter API lets third-party applications read and write data. Use it to write and post tweets, share tweets, and read profiles. This API is especially effective for downloading and analyzing large amounts of tweets about specific topics. Learn more about using Twitter’s API in our guide.
The Instagram Basic Display API offers access to profile information, photos, and videos. You can utilize this API and others to build apps that pull this user information and integrate it into your own product. Instagram also has a Graph API available for professional Instagram accounts to manage their online activities.
Spotify’s web API allows clients to request information about artists, songs, albums, and playlists on its platform. You can also use it to add songs to playlists, pause and play music, shuffle songs, and a lot more.
All of HubSpot’s APIs are made with REST conventions and designed for robust integrations that help businesses get the most value out of HubSpot’s tools. You can add advanced functionality to HubSpot’s powerful marketing software and sync your HubSpot account with other useful tools.
It’s a common belief that REST APIs will soon be the industry standard for web-based communications, and for good reason. They enable any two online applications to interact and share data, regardless of their sizes or capabilities. Through REST, a small startup can interface with a massive government agency, and vice versa.
Software tools can create amazingly powerful and innovative systems by working together, which is something any growing online platform should want to be a part of. If you’re looking to connect your app to the software world, don’t sleep on REST.
Originally published Jul 27, 2020 7:00:00 AM, updated October 28 2021