What Is a REST API? A Plain-English Guide With Examples

If you've ever connected two apps, added a booking form to a website or asked a developer how your shop talks to your email tool, there's a good chance a REST API was doing the work in the background. The term gets thrown around a lot, and it's easy to nod along without knowing what it means.

I've pulled together a plain-English guide from the reference material developers use every day, mainly MDN Web Docs and the background on Roy Fielding's original work. You won't need to write code to follow it, but by the end you'll understand what a developer means when they say an app has a REST API.

REST API meaning in plain English

An API, or application programming interface, is a set of rules that lets one piece of software ask another for something. REST stands for Representational State Transfer. MDN describes REST as a group of software architecture design constraints that bring about efficient, reliable and scalable distributed systems.

Put simply, a REST API lets a client, such as a website, a mobile app or another server, ask a server for a resource and get back a copy of it in a standard format. The resource might be a customer record, a blog post or a list of orders. MDN also makes a helpful point for beginners: people often call any HTTP API a REST API, even when it doesn't follow every REST rule, so you can treat a REST API as an HTTP service you call with standard web tools.

Here's an analogy I like. Think of a restaurant. You don't walk into the kitchen; you read the menu and ask the waiter. The menu is the API's documentation, the waiter carries your request, and the kitchen is the server. You get your dish without ever seeing how it's cooked.

Where REST came from: Roy Fielding's dissertation

The term was introduced by computer scientist Roy Fielding in 2000, in his doctoral dissertation at the University of California, Irvine, titled Architectural Styles and the Design of Network-based Software Architectures. He used it to describe how a large, distributed hypermedia system like the Web should behave.

The six REST constraints

Fielding set out a list of constraints. An API that follows them is described as RESTful:

• Client and server. The client and the server are separate and talk through a well-defined interface, so each can change without breaking the other.
• Stateless. The server doesn't store the client's session between requests. Each request carries everything the server needs to handle it.
• Cacheable. Responses say whether they can be cached, so a client can reuse data rather than asking again.
• Uniform interface. Resources are identified by addresses and handled in one consistent way, which is what makes REST APIs feel familiar from one service to the next.
• Layered system. A client can't normally tell whether it's talking to the end server or something in between, such as a cache or load balancer.
• Code on demand (optional). A server can send code for the client to run, although this one's optional.

REST API resources, endpoints and JSON

In REST, everything is a resource, and each resource has its own address, called an endpoint. A customer database might expose endpoints like /customers for the full list and /customers/42 for one customer. The resource itself is separate from the way it's represented when it's sent to you.

These days that representation is usually JSON, short for JavaScript Object Notation. MDN describes JSON as a data-interchange format that can represent numbers, true or false values, text, lists and named groups of values. It's easy for people to read and easy for programs to parse, which is why so many APIs use it. A customer record in JSON is just a list of labelled values, such as a name, an email address and a sign-up date.

HTTP methods a REST API uses

A REST API uses the standard HTTP methods to say what you want to do with a resource. MDN's reference lists them, and these are the ones you'll meet most often:

Method	What it does	Everyday example
GET	Requests a representation of a resource and should only retrieve data	Show me customer 42
POST	Submits data to a resource, often creating something new	Add a new customer
PUT	Replaces the current version of a resource with the data sent	Replace customer 42's whole record
PATCH	Applies partial changes to a resource	Update only customer 42's email
DELETE	Deletes the specified resource	Remove customer 42

REST API status codes you'll see

Every response comes back with a three-digit HTTP status code that tells the client how things went. MDN groups them into five classes: informational (100 to 199), successful (200 to 299), redirection (300 to 399), client errors (400 to 499) and server errors (500 to 599). The ones you'll see most with a REST API are:

• 200 OK: the request worked.
• 201 Created: the request worked and a new resource was created.
• 204 No Content: it worked, but there's nothing to send back.
• 400 Bad Request: the server won't process it because of something it sees as a client error.
• 401 Unauthorized: you need to authenticate first.
• 403 Forbidden: the server knows who you are, but you don't have access.
• 404 Not Found: the resource can't be found.
• 500 Internal Server Error: something went wrong on the server.

A REST API request walked through in words

Here's what happens when an app asks for one customer's details. The app sends a GET request to the endpoint /customers/42 and includes a key or token to show it's allowed in. The server checks the key, finds customer 42 and sends back a 200 OK status with the record as JSON. The app reads the JSON and shows the name and email on screen.

If the app sends the same request without a valid key, it'll get 401 back. If customer 42 doesn't exist, it'll get 404. Because REST is stateless, the next request has to carry the key again; the server hasn't remembered anything from the last one. All of this happens between the visible part of an app and its server, which is the split I explain in front end vs back end.

REST API vs GraphQL and webhooks

REST isn't the only way to build an API. GraphQL describes itself as a query language for APIs, and its own learning guide explains how a client can structure queries to request exactly the data it needs. With REST, the server decides what each endpoint returns, so you might get more fields than you need or need several calls to collect related data.

REST APIs also work on a request and response basis: your app has to ask. If you want a service to tell you the moment something happens, such as a new order, that's where webhooks come in, and I've compared the two in API vs webhook.

Common REST API mistakes to avoid

• Using GET to change data. GET should only retrieve.
• Returning 200 OK for every response, even errors, which makes problems hard to spot.
• Putting keys or tokens in places they could leak, such as shared code repositories.
• Relying on the server to remember a session, which breaks the stateless rule.
• Skipping documentation. A REST API is only as easy to use as its docs.

Learning more about REST APIs and sharing what you know

MDN Web Docs is a reliable free place to read more about HTTP methods, status codes and JSON. Once you're confident, writing about your own API projects is a good way to help others and build your name.

Developers who document APIs well can share that work on API and developer blogs that accept articles.

Frequently asked questions

Is every HTTP API a REST API?

Not strictly. MDN notes that people often call HTTP APIs RESTful even when they don't follow every REST constraint, so the label is used loosely.

What does stateless mean in REST?

It means the server doesn't keep the client's session between requests. Each request has to include everything needed to handle it, such as the access key.

Does a REST API have to use JSON?

No. REST describes how resources are identified and handled, not one format. JSON is the most common choice because it's light and easy to read, but XML and HTML are also possible.

Who invented REST?

Roy Fielding introduced the term in his doctoral dissertation at the University of California, Irvine, in 2000.

What's the difference between PUT and PATCH?

PUT replaces the whole resource with what you send, while PATCH applies partial changes, such as updating one field.