What Is a REST API? How Apps Talk to Each Other
REST APIs are how most web apps communicate. Here's what they are, how they work, and what you need to know when building or consuming one.
The Problem REST APIs Were Built to Solve
Every web app you use is really a collection of different systems talking to each other. Your frontend asks your backend for data. Your backend asks a payment provider to charge a card. That payment provider asks a fraud detection service to verify the transaction. All of that communication has to happen reliably, across different languages, different servers, and different companies.
REST APIs are the standard that makes most of that communication work. If you’re building web apps, consuming third-party services, or working with AI agents that call external tools, you’ll run into REST APIs constantly. This article explains what they are, how they work, and what you actually need to know when building or consuming one.
What Is a REST API?
A REST API (Representational State Transfer Application Programming Interface) is a way for two systems to communicate over HTTP using a set of agreed-upon conventions.
Break that down:
- API — a contract that defines how one piece of software can talk to another. You call a specific endpoint with specific inputs, and you get a specific output back.
- REST — a set of architectural constraints that make APIs predictable, stateless, and consistent. REST was defined by Roy Fielding in his 2000 doctoral dissertation, and it’s been the dominant style for web APIs ever since.
- HTTP — the same protocol your browser uses to load web pages. REST APIs ride on top of it.
The result is a standardized, widely-understood way to expose data and functionality over the internet. When you open a weather app and see today’s forecast, a REST API fetched that data. When you log in to a site with Google, a REST API is handling the authentication handshake. When you process a payment on Stripe, you’re calling Stripe’s REST API.
Understanding what’s happening in the backend of any web application usually means understanding REST APIs.
The Six REST Constraints
“REST” isn’t just a vague label — it refers to six specific architectural constraints that Fielding defined. In practice, most developers don’t think about all six explicitly, but they matter because they explain why REST works as well as it does.
1. Client-Server Architecture
The client (usually a browser or mobile app) is separated from the server (where data lives and logic runs). They communicate through a well-defined interface. This separation means you can change the frontend without touching the backend, and vice versa.
2. Statelessness
Every request from the client to the server must contain all the information the server needs to fulfill it. The server doesn’t store any session state between requests. If you need authentication, you include the token in every request. If you need context, you send it along.
This makes REST APIs easier to scale — any server can handle any request, because there’s no session state to synchronize across servers.
3. Cacheability
Responses should indicate whether they can be cached. A list of products that rarely changes can be cached aggressively. A user’s current balance should not be. Proper caching reduces server load and speeds up clients.
4. Uniform Interface
All REST APIs expose resources through a consistent interface: a URL identifies the resource, and HTTP methods indicate what you want to do with it. This consistency is what makes REST APIs predictable across providers.
5. Layered System
The client doesn’t need to know whether it’s talking directly to the actual server, a load balancer, a CDN, or a proxy. The system can be layered without the client caring.
6. Code on Demand (Optional)
Servers can optionally send executable code to clients (like JavaScript). This is rarely used in practice and is the only optional constraint.
Most APIs that call themselves REST don’t strictly implement all six. What matters in practice is statelessness, uniform interface, and client-server separation.
How REST APIs Work: The Request-Response Cycle
Every REST API interaction follows the same basic pattern: a client sends a request, a server processes it and returns a response.
Anatomy of a REST Request
A REST request has four parts:
1. The URL (endpoint)
The URL identifies the resource you’re working with. For example:
https://api.example.com/users/42This refers to the user with ID 42. The base URL (api.example.com) is the API host. The path (/users/42) identifies the specific resource.
2. The HTTP method
The method tells the server what operation you want to perform. The five most common:
| Method | What it does |
|---|---|
GET | Retrieve a resource |
POST | Create a new resource |
PUT | Replace an existing resource entirely |
PATCH | Update part of an existing resource |
DELETE | Remove a resource |
3. Headers
Key-value pairs that carry metadata about the request. The most important ones for REST APIs:
Authorization— your API key or tokenContent-Type— tells the server what format you’re sending (usuallyapplication/json)Accept— tells the server what format you want back
4. The request body
Used with POST, PUT, and PATCH requests to send data. Almost always formatted as JSON.
{
"name": "Jane Smith",
"email": "jane@example.com"
}Anatomy of a REST Response
The server responds with:
1. A status code
A three-digit number that tells you what happened. The ranges:
| Range | Meaning |
|---|---|
| 2xx | Success |
| 3xx | Redirect |
| 4xx | Client error (your fault) |
| 5xx | Server error (their fault) |
The most common specific codes:
200 OK— success, here’s your data201 Created— resource was created204 No Content— success, nothing to return400 Bad Request— your request was malformed401 Unauthorized— you’re not authenticated403 Forbidden— you’re authenticated but don’t have permission404 Not Found— the resource doesn’t exist422 Unprocessable Entity— validation failed429 Too Many Requests— you’re rate limited500 Internal Server Error— something broke on the server
2. Response headers
Metadata about the response — things like Content-Type, rate limit remaining, cache directives.
3. The response body
The actual data you asked for, almost always in JSON.
{
"id": 42,
"name": "Jane Smith",
"email": "jane@example.com",
"created_at": "2026-03-15T09:00:00Z"
}REST API Endpoints in Practice
An API is essentially a collection of endpoints. Each endpoint represents a resource or an action.
Resource-Based Design
Good REST API design organizes endpoints around resources (nouns), not actions (verbs). The HTTP method handles the verb.
Here’s what a well-designed users API looks like:
| Method | Endpoint | What it does |
|---|---|---|
GET | /users | List all users |
POST | /users | Create a new user |
GET | /users/42 | Get user with ID 42 |
PATCH | /users/42 | Update user 42 |
DELETE | /users/42 | Delete user 42 |
GET | /users/42/posts | Get all posts by user 42 |
Notice the pattern: the URL identifies what you’re working with, and the method identifies what you’re doing to it.
Query Parameters
For filtering, sorting, and pagination, you typically use query parameters:
GET /users?role=admin&sort=created_at&limit=25&page=2These are appended to the URL after a ? and formatted as key=value pairs joined by &.
Path Parameters
When you need to identify a specific resource, you embed the identifier in the path:
GET /orders/8821/items/3This reads: get item 3 from order 8821.
Authentication: How REST APIs Know Who You Are
Since REST is stateless, you need to prove your identity on every request. There are a few common approaches.
API Keys
The simplest approach. You include a secret key in the request header:
Authorization: Bearer sk_live_abc123...The server checks that key against its database. Simple, but if the key leaks, anyone can use it.
OAuth 2.0
A more sophisticated system where users grant apps limited access to their accounts without sharing passwords. When you “Sign in with Google” or authorize a GitHub app, you’re going through OAuth. The result is an access token that the app uses for subsequent requests.
JWT (JSON Web Tokens)
A self-contained token format that carries claims (like user ID and permissions) in a signed, compact string. The server issues a JWT on login, and the client sends it with every subsequent request. The server can verify the token’s signature without hitting a database.
If you want to go deeper on auth implementation, there’s a solid breakdown in the guide on adding authentication to your web app.
REST vs. Other API Styles
REST is the most common API style, but it’s not the only one. Here’s how it compares.
REST vs. GraphQL
GraphQL is a query language for APIs developed by Meta. Instead of hitting multiple endpoints to get related data, you write a single query that specifies exactly what fields you want:
query {
user(id: "42") {
name
email
posts {
title
publishedAt
}
}
}GraphQL reduces over-fetching (getting more data than you need) and under-fetching (needing multiple requests for related data). But it adds complexity on both ends. REST is simpler to build, easier to cache, and sufficient for most use cases.
REST vs. gRPC
gRPC is a high-performance protocol developed by Google that uses Protocol Buffers (a binary format) instead of JSON. It’s faster and more efficient than REST, but requires more setup and isn’t browser-native. It’s common for internal service-to-service communication where performance matters a lot.
REST vs. WebSockets
REST is request-response: the client asks, the server answers, the connection closes. WebSockets are persistent connections that allow real-time bidirectional communication. REST is better for CRUD operations; WebSockets are better for live updates, chat, or collaborative editing.
How REST APIs Power Modern AI Applications
If you’re building apps with AI features, REST APIs are everywhere. AI agents call REST APIs to take actions in the world: search the web, query a database, send emails, look up customer records in a CRM.
Large language models themselves are exposed via REST APIs. When you call OpenAI, Anthropic, or Google, you’re sending a POST request with your prompt and getting back a completion. The API is the interface between your application and the model.
More recently, the Model Context Protocol (MCP) has emerged as a standard for connecting AI models to external data sources and tools — but even MCP servers typically sit on top of REST APIs underneath.
If you’re curious how AI agents make decisions that involve calling multiple APIs in sequence, multi-step reasoning is worth understanding.
The ability to consume and integrate REST APIs is becoming a core skill not just for backend developers, but for anyone building AI-powered applications.
Designing a Good REST API
If you’re building an API — not just consuming one — these principles matter.
Use Consistent Naming Conventions
Stick to plural nouns for resource collections (/users, not /user). Use kebab-case or snake_case consistently. Don’t mix them.
Version Your API
Include a version in your URL from day one:
https://api.example.com/v1/usersWhen you make breaking changes, you release /v2 without breaking existing clients.
Return Meaningful Error Messages
A 400 response with no body is useless. Include an error code and a human-readable message:
{
"error": "validation_failed",
"message": "Email is already in use.",
"field": "email"
}Handle Pagination
Never return unbounded lists. Use limit/offset or cursor-based pagination, and include metadata so clients know if there are more pages:
{
"data": [...],
"pagination": {
"total": 1847,
"page": 2,
"limit": 25,
"has_more": true
}
}Document Everything
An undocumented API is nearly useless. Use OpenAPI/Swagger to generate documentation that developers can interact with directly. Good API documentation is one of the biggest factors in adoption.
The database schema underneath your API matters too — a well-designed schema makes it much easier to expose clean, consistent endpoints.
REST API Security: What You Need to Know
API security is where a lot of apps get into trouble. A few essentials:
Always use HTTPS. Never expose a REST API over plain HTTP. Every request must be encrypted in transit.
Validate inputs on the server. Never trust what a client sends. Validate data types, lengths, formats, and ranges before processing.
Implement rate limiting. Without it, anyone can hammer your API with thousands of requests per second. Rate limiting protects your infrastructure and prevents abuse.
Use the principle of least privilege. API tokens should only have access to what they need. A read-only analytics integration doesn’t need write access to your users table.
Rotate and revoke credentials. API keys should be rotatable. If a key is compromised, you need to be able to invalidate it immediately without taking down the whole system.
Log everything. API request logs are invaluable for debugging, auditing, and detecting unusual access patterns.
How Remy Handles REST APIs
If you’re building a full-stack app, your REST API is essentially the contract between your frontend and your backend. It’s where a lot of the complexity lives — defining endpoints, validating inputs, connecting to the database, handling errors, managing auth.
Remy approaches this differently. Instead of writing API routes by hand, you describe what your app does in a spec — annotated prose that defines your data models, business rules, and user flows. Remy compiles that spec into a working full-stack app: TypeScript backend, SQL database, auth, deployment, everything.
The REST API layer gets generated from the spec. Endpoints exist because they’re implied by the application’s behavior, not because you manually defined each route and handler. And because the spec is the source of truth, when you change what the app does, the API changes with it.
This connects to a broader idea worth reading about: spec-driven development as a higher-level abstraction for building apps. The spec is the program. The code — including the API — is compiled output.
If you want to skip the boilerplate and build something that works end-to-end, try Remy at mindstudio.ai/remy.
Frequently Asked Questions
What is the difference between an API and a REST API?
An API (Application Programming Interface) is a general term for any contract that lets software systems communicate. A REST API is a specific type of API that communicates over HTTP and follows the REST architectural constraints: statelessness, a uniform interface, client-server separation, and cacheability. Other API styles include GraphQL, gRPC, and SOAP. When most people say “API” in a web context, they usually mean REST API.
What does stateless mean in REST?
Stateless means the server doesn’t remember anything about previous requests. Every request has to be self-contained — it must include all the information the server needs (authentication, context, data) to process it. The server processes the request and forgets about it. The client is responsible for maintaining any state between calls.
What is JSON and why do REST APIs use it?
JSON (JavaScript Object Notation) is a lightweight text format for representing structured data. It’s human-readable, language-agnostic, and easy to parse. REST APIs use JSON because virtually every programming language can read and write it, and it maps naturally to the object structures most programming languages use. Some older APIs use XML, but JSON has largely won.
What is an API key and how does it work?
An API key is a secret string that identifies you (or your application) to an API. You include it in your request headers, and the server uses it to look up who you are, verify you’re authorized, and track your usage. API keys are simple but should be treated like passwords — never hardcode them in client-side code or commit them to public repositories.
What is the difference between GET and POST requests?
GET requests retrieve data without modifying anything. They have no request body, and their parameters go in the URL. POST requests create new resources or submit data for processing. They carry a request body, usually JSON. The key distinction: GET should be idempotent (calling it multiple times has the same effect as calling it once), while POST typically creates something new each time.
How do REST APIs handle errors?
Through HTTP status codes plus a response body with more detail. The status code gives you the category (4xx for client errors, 5xx for server errors), and the response body explains what went wrong. Good APIs return a consistent error format with a machine-readable error code (useful for handling errors programmatically) and a human-readable message (useful for debugging).
Key Takeaways
- A REST API is a standardized way for two systems to communicate over HTTP, using URLs to identify resources and HTTP methods to indicate what operation to perform.
- Every REST interaction is a request (method + URL + headers + optional body) and a response (status code + headers + optional body).
- Status codes tell you what happened: 2xx is success, 4xx is a client error, 5xx is a server error.
- REST APIs are stateless — every request must include all the information the server needs.
- Authentication happens through headers on every request, commonly via API keys, OAuth tokens, or JWTs.
- REST is the dominant API style for web applications, though GraphQL and gRPC serve specific use cases better.
- AI applications rely heavily on REST APIs — both to expose model capabilities and to let agents take actions in external systems.
If you want to build an app with a real backend and a proper API without writing every route by hand, try Remy — it compiles your application spec into a full-stack app, API included.
