REST API
Also known as: RESTful API, REST, Representational State Transfer, REST web service
A REST API is a way for software systems to communicate over the web using standard HTTP requests.
Each piece of data, such as a customer or order, has its own web address, and apps use methods like GET to read, POST to create, PUT or PATCH to update, and DELETE to remove it, usually exchanging data in JSON. REST is the most common API style for web and mobile apps. While REST is simple and widely supported, it can require many requests for complex data, which is one reason alternatives like GraphQL exist.
REST API, explained at three levels
At home
A REST API is like a restaurant with a clear menu. You ask for a dish by name, and the kitchen sends it back in a standard format.
At work
REST APIs let business systems, such as a website and an inventory system, share data automatically.
At home
When a weather app shows the forecast, it's often calling a REST API with a web address like /forecast?city=Ottawa and getting JSON back.
At work
REST APIs use HTTP status codes such as 200 for success, 404 for not found, and 429 for too many requests. OpenAPI documents describe endpoints, inputs, and outputs.
At home
Many services let you create API keys to connect your own tools. In my opinion, treat those keys like passwords and never share them.
At work
Secure REST APIs with strong authentication, authorization checks on every object, rate limiting, input validation, and logging. Broken object-level authorization is one of the most common API flaws.
Real-world examples
At home
Lena built a small app that shows bus arrival times. It calls her city's transit REST API and displays the next buses at her stop.
At work
Thomas leads integrations at a Montreal logistics company. He documented their REST API with OpenAPI so partners could connect in days instead of weeks.
How it compares
| feature | REST API | GraphQL |
|---|---|---|
| Requests | Many endpoints | Usually one endpoint |
| Data returned | Fixed by server | Chosen by client |
| Simplicity | Very familiar | More setup |
| Caching | Easy with HTTP | More complex |
REST is simple and familiar. GraphQL is flexible for complex data.
For analysts
In integration requirements, I'd specify the API style, authentication, error handling, and rate limits up front. Vague 'it'll have an API' promises cause delays later.
History & origin
Computer scientist Roy Fielding described REST, short for Representational State Transfer, in his 2000 doctoral dissertation at the University of California, Irvine, drawing on his work on the HTTP standard. Through the 2000s, companies such as Flickr, Amazon, and Twitter offered REST-style APIs that were simpler than older SOAP-based web services. The OpenAPI Specification, which began as Swagger in 2011, became the standard way to describe REST APIs. GraphQL, released by Facebook in 2015, offered an alternative for complex data needs. In my view, REST became the default not because it's perfect, but because it fits how the web already works.