API 101: What Is a REST API?

August 28, 2020

REpresentational State Transfer (REST) is a software architectural style that developers apply to web application programming interfaces (APIs). (Learn more fundamentals in our What Is an API? and What Is a SOAP API? posts.) REST APIs are the most common APIs used across the web today because the REST pattern provides simple, uniform interfaces. These can be used to make data, content, algorithms, media, and other digital resources available through web URLs, so that they can be consumed within web, mobile, and device applications.

A URL—universal resource locator—is an essential aspect of the web, allowing us to locate resources within various online domains like Facebook, Twitter, and our own domains. REST is just a more standardized way for these domains to make resources available across their websites, and within their mobile applications, while also making the same resources available to developers via a public API. Developers then have a common way to define and locate a variety of digital resources that they put to work across the applications and integrations they are building each day.

REST practitioners will always have lots of opinions about what is REST and what isn’t—and there are plenty of technical details to consider when designing a REST API. But the basic idea is this: REST helps you better organize your digital resources and the operations you can perform against them. It’s about establishing a shared language to describe your digital capabilities and enable wider collaboration around their web usage.

Read about REST API examples—and how you can explore tons in Postman’s public collection—in our recent blog post here.

Working with resources and REST

There is plenty of nuance to consider from Roy Fielding’s original dissertation on REST, but understanding resources is critical to understanding REST. To learn what a resource is, and how it can be represented using APIs, let’s consider my own personal Facebook presence, where I am a resource. I can view an HTML representation of my resource at:

GET https://www.facebook.com/kinlane/

My profile is a single resource available on Facebook. I can view a representation of that resource in HTML using that URL in my web browser. I can also view another representation of it using the Facebook Graph API.

GET https://graph.facebook.com/v7.0/me

To access the API, I have to be authenticated and provide a token that represents my Facebook identity. But when I make a request to this resource within the Facebook Graph API, I am given a JSON representation of my Facebook profile. I can take this JSON and use it in other applications, allowing me to access “me” on the Facebook platform across the web and in mobile applications. This is just one resource Facebook provides, offering up a buffet of digital resources for me to consume as a developer.

Comments: GET https://graph.facebook.com/v7.0/comments
Friends: GET https://graph.facebook.com/v7.0/friends
Images: GET https://graph.facebook.com/v7.0/images
Links: GET https://graph.facebook.com/v7.0/links
Likes: GET https://graph.facebook.com/v7.0/likes
Location: GET https://graph.facebook.com/v7.0/locations
Messages: GET https://graph.facebook.com/v7.0/messages
Notifications: GET https://graph.facebook.com/v7.0/notifications
Pages: GET https://graph.facebook.com/v7.0/pages
Payments: GET https://graph.facebook.com/v7.0/payments
Share: GET https://graph.facebook.com/v7.0/share
Posts: GET https://graph.facebook.com/v7.0/posts
Places: GET https://graph.facebook.com/v7.0/places
Videos: GET https://graph.facebook.com/v7.0/videos

Naming, organizing, and making digital resources in this way are the seeds of REST. Now that you have your resources well-defined, you can GET these resources. More importantly, you can also manage each resource’s state over time—adding new ones, updating, transforming, and deleting existing ones. This allows for a handful of operations on each resource using HTTP methods:

GET: https://graph.facebook.com/v7.0/images
POST: https://graph.facebook.com/v7.0/images
PUT: https://graph.facebook.com/v7.0/images
DELETE: https://graph.facebook.com/v7.0/images

The four methods listed above allow you to get, add, update, and delete images on Facebook respectively. Facebook uses REST to allow developers to manage the state of image resources using simple URLs, leveraging the web’s backbone, HTTP, to make data accessible and configurable using low-cost web infrastructure.

Ultimately, REST isn’t a specification; it is simply an architectural style to consider as you plan each API. And it’s popular because it helps simplify and standardize how we share data, content, and media using the web.