REST APIs: How They Work and What You Need to Know

Download Now: How to Use an API
Jamie Juviler
Jamie Juviler

Published:

In the interconnected world of software applications, sharing data between systems has become the cornerstone of functionality and service diversity. One key player that has revolutionized this data sharing and communication is REST APIs, acting as the enabler for integrations.

Person writing REST APIs

 

These APIs provide a standardized way for two applications to communicate, enabling your software to interact efficiently with various other services, thereby enhancing its capabilities and user experience.

In this guide, I’ll explain what a REST API is and why they’re so useful.

Before getting started, you should be familiar with what APIs are and how they work.

Download Now: How to Use an API [Free Ebook]

What is a REST API?

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.

 

We're committed to your privacy. HubSpot uses the information you provide to us to contact you about our relevant content, products, and services. You may unsubscribe from these communications at any time. For more information, check out our Privacy Policy.

Free Ebook: How to Use an API

Fill out the form to learn how to use an API.

  • HTML Code Templates
  • CSS Code Templates
  • JavaScript Code Templates
Loading your download form

You're all set!

Click this link to access this resource at any time.

Access now
Learn more
Featured Resource

Free Ebook: How to Use an API

Fill out the form to learn how to use an API.

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:

 

GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails

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.

After receiving and validating the request, the host returns information about the target resource. Usually, the information is back sent in a format called JSON, which stands for JavaScript Object Notation. JSON lays out all the contents of a resource in a lightweight format that humans can easily read.

This page in YouTube's API documentation shows the format of a Youtube Video resource formatted in JSON. Can you identify some of the different resources provided?

3. Stateless

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.

We're committed to your privacy. HubSpot uses the information you provide to us to contact you about our relevant content, products, and services. You may unsubscribe from these communications at any time. For more information, check out our Privacy Policy.

Free Ebook: How to Use an API

Everything you need to know about the history and use of APIs.

  • A History of APIs
  • Using APIs
  • Understanding API Documentation
  • And more!
Loading your download form

You're all set!

Click this link to access this resource at any time.

Access now
Learn more

5. Cacheable

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 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:

Twitter

What we like: The Twitter API enables third-party applications to read and write data, offering a diverse range of functionalities.

Best for: Applications looking to integrate social media functionalities, especially those related to tweeting and profile management.

Pro Tip: 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.

Instagram

What we like: The Instagram Basic Display API offers access to profile information, photos, and videos.

Best for: Applications aiming to integrate photo and video-sharing functionalities.

Pro Tip: Utilize this API to pull user information and integrate it into your product for an enhanced user experience.

Spotify

What we like: Spotify’s web API allows clients to request information about artists, songs, albums, and playlists.

Best for: Music-related applications looking to integrate features related to music streaming.

Pro Tip: Use this API to add songs to playlists, pause and play music, shuffle songs, and more for an enriched musical experience.

HubSpot

What we like: All of HubSpot’s APIs are made with REST conventions and are designed for robust integrations.

Best for: Business applications seeking to enhance their marketing and customer management functionalities.

Pro Tip: Use HubSpot's APIs to add advanced functionality to your marketing software and sync your application with other useful tools.

For more REST API examples that you can use for your business, check out our list of our favorite free and open APIs for marketers.

We're committed to your privacy. HubSpot uses the information you provide to us to contact you about our relevant content, products, and services. You may unsubscribe from these communications at any time. For more information, check out our Privacy Policy.

Free Ebook: How to Use an API

Everything you need to know about the history and use of APIs.

  • A History of APIs
  • Using APIs
  • Understanding API Documentation
  • And more!
Loading your download form

You're all set!

Click this link to access this resource at any time.

Access now
Learn more

Don’t Sleep on REST

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.

api

Related Articles

We're committed to your privacy. HubSpot uses the information you provide to us to contact you about our relevant content, products, and services. You may unsubscribe from these communications at any time. For more information, check out our Privacy Policy.

Everything you need to know about the history and use of APIs.

CMS Hub is flexible for marketers, powerful for developers, and gives customers a personalized, secure experience

START FREE OR GET A DEMO