How a REST API Works

Audience

This guide is for anyone who needs to understand how REST APIs work:

• Backend developers building APIs for web and mobile applications
• Frontend developers consuming APIs to build user interfaces
• Product managers defining features that rely on API integration
• Security professionals reviewing API architectures and implementations
• Technical architects designing systems that communicate over HTTP
• Anyone curious about how modern applications talk to each other

No prior API experience required—we’ll start from the fundamentals.

Goal

After reading this guide, you’ll understand:

• What problem APIs solve and why they exist
• How HTTP enables communication between systems
• What REST means and why it became the dominant API style
• How resources, methods, and status codes work together
• What makes an API “RESTful” (and what doesn’t)
• Common patterns and anti-patterns in REST API design

You won’t be an API architect yet, but you’ll have a solid mental model of how REST APIs work and why they’re designed the way they are.

1. What Problem Do APIs Solve

Imagine you’re building a mobile app that shows a user’s bank account balance. Your app runs on a phone. The bank’s database runs on a server thousands of miles away. These two systems can’t share memory—they’re physically separate machines.

The fundamental problem: How do these systems communicate reliably, securely, and consistently?

Enter the API (Application Programming Interface). An API is a contract that defines how two systems exchange information. It’s like a restaurant menu: you (the client) see what you can order (available operations), and the kitchen (the server) knows what to prepare when you place an order (request).

graph LR
    A[Mobile App
Client] -->|Request| B[Bank API
Server]
    B -->|Response| A
    style A fill:#e3f2fd
    style B fill:#fff3e0

APIs solve three critical problems:

1. Separation of concerns: The mobile app doesn’t need to know how the bank stores data. It just needs to know how to ask for it.
2. Stable contracts: As long as the API doesn’t change, both systems can evolve independently.
3. Communication across boundaries: Different teams, organizations, or even companies can integrate their systems through well-defined APIs.

Key terms introduced:

• System: Any software application or service (mobile app, web server, database)
• Client: The system making requests (your app)
• Server: The system responding to requests (the bank’s API)
• Contract: The agreed-upon rules for communication (what requests are valid, what responses to expect)

2. What is an API (No Unnecessary Jargon)

Let’s clear up some confusion.

An API is not just a URL like https://api.bank.com/accounts. That’s an endpoint—a specific address within an API.

An API is the entire interface a server exposes. Think of it as the full menu at a restaurant, not just one dish. The API includes:

• All available operations (get account balance, transfer money, view transactions)
• How to request each operation (what data to send)
• What responses to expect (success, errors, data formats)

API vs. Web App: What’s the Difference?

Both web apps and APIs use HTTP and respond to requests. So what’s the difference?

Example: When you visit https://bank.com in your browser, you get a web page with buttons and forms. When your mobile app requests https://api.bank.com/accounts, it gets structured data:

{
  "accountNumber": "123456789",
  "balance": 5432.10,
  "currency": "USD"
}

What “Consuming an API” Means

When developers say they’re “consuming an API,” they mean their code is making HTTP requests to that API and processing the responses. The client (consumer) depends on the API contract staying stable.

Breaking analogy: If a restaurant suddenly changes “Burger” to mean “Salad” without notice, customers will be confused. Similarly, if an API changes balance from a number to a string, all client apps break.

What “Consuming an API” Means (Example)

Here’s what a typical API response looks like:

{
  "user": {
    "id": 123,
    "name": "Alice",
    "email": "[email protected]"
  }
}

3. Why HTTP is the Common Language

You could invent your own protocol for client-server communication, but why would you? HTTP (Hypertext Transfer Protocol) is already universal, battle-tested, and understood by every programming language.

What HTTP Really Is

HTTP is a request-response protocol. The client sends a request, and the server sends back a response. That’s it.

sequenceDiagram
    participant C as Client
    participant S as Server
    C->>S: [HTTP Request](https://reference.apios.info/terms/request/)
    Note over C,S: Method, Path, Headers, Body
    S->>C: [HTTP Response](https://reference.apios.info/terms/response/)
    Note over C,S: Status Code, Headers, Body

Every HTTP request includes:

1. Method: What action to perform (GET, POST, PUT, DELETE, etc.)
2. Path: Which resource to act on (/users/123)
3. Headers: Metadata about the request (authentication, content type)
4. Body (optional): Data being sent (e.g., user details to create)

Every HTTP response includes:

1. Status code: Did it work? (200 OK, 404 Not Found, 500 Error, etc.)
2. Headers: Metadata about the response
3. Body (optional): Data being returned

What Stateless Means

HTTP is stateless. The server doesn’t remember previous requests. Each request must contain everything the server needs to understand it.

Why this matters: If you make a request to get user 123’s profile, then immediately request user 123’s transactions, the server doesn’t remember you just asked about user 123. Each request is independent.

How clients handle this: They send authentication tokens (like JWT) with every request, so the server knows who’s asking without remembering previous interactions.

GET /users/123/transactions [HTTP/1.1](https://reference.apios.info/terms/http-1-1/)
Host: api.bank.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Every request carries its own context.

4. What REST Means (Not as Religion)

REST stands for Representational State Transfer. It’s not a protocol or a standard—it’s an architectural style defined by Roy Fielding in his 2000 PhD dissertation.

REST as a Style, Not a Law

Think of REST like architectural styles in buildings. “Victorian,” “Modern,” or “Brutalist” describe design principles, but two Victorian houses can look very different. REST is similar: it’s a set of principles for designing networked applications.

Core REST principles:

1. Client-Server separation: Clients and servers are independent. They only communicate through the API.
2. Stateless: Each request contains all necessary information. The server doesn’t store client state between requests.
3. Cacheable: Responses should indicate whether they can be cached to improve performance.
4. Uniform interface: Resources are identified by URLs, and you interact with them using standard HTTP methods.
5. Layered system: Client can’t tell if it’s connected directly to the server or through intermediaries (load balancers, proxies).

What REST Brings to the Table

REST APIs leverage HTTP’s existing semantics instead of inventing new ones. Benefits:

• Predictability: If you’ve used one REST API, you understand the patterns used by others.
• Tooling: HTTP debuggers, proxies, caches, and CDNs work out of the box.
• Scalability: Statelessness and cacheability make it easier to scale servers horizontally.

What Happens When You Don’t Follow It

Not following REST isn’t a sin—it’s a tradeoff. But here’s what you lose:

• Confusion: An API that uses POST for everything is harder to understand and debug.
• Missed optimizations: Browsers and proxies cache GET requests by default. If you use POST for reads, you lose free caching.
• Breaking HTTP semantics: Tools assume GET is safe (no side effects). If your GET request deletes data, automated crawlers might wreck your system.

REST isn’t dogma, but its principles align with how HTTP was designed to work.

5. Resources, Not Actions

In REST, you don’t think in terms of actions (verbs). You think in terms of resources (nouns).

What a Resource Is

A resource is any entity your API exposes: a user, an account, a transaction, a document, a setting. Each resource has a unique identifier (URL).

Examples:

• /users/123 → User with ID 123
• /accounts/456 → Account with ID 456
• /accounts/456/transactions → Collection of transactions for account 456

Key insight: Resources can be individual items (singular) or collections (plural).

graph TD
    A["/accounts"] -->|Collection| B[All accounts]
    C["/accounts/456"] -->|Individual| D[Specific account]
    E["/accounts/456/transactions"] -->|Sub-collection| F[Transactions for account 456]
    style A fill:#e1f5fe
    style C fill:#fff9c4
    style E fill:#f3e5f5

Why /users/123 is Not a Verb

Bad API design:

POST /createUser
POST /getUser
POST /deleteUser

This is RPC (Remote Procedure Call) over HTTP. You’re exposing actions as endpoints.

Good REST design:

POST /users          → Create user
GET /users/123       → Get user
DELETE /users/123    → Delete user

The resource is /users or /users/123. The action is the HTTP method (POST, GET, DELETE). This separation keeps URLs clean and semantics clear.

Why POST /login is Already a Concession

Strictly speaking, /login isn’t a resource—it’s an action. In pure REST, you’d model it as:

POST /sessions    → Create a new session (login)
DELETE /sessions/xyz → Destroy session (logout)

But most APIs use POST /login because it’s intuitive. This is fine. REST is a guide, not a straitjacket. The key is consistency: if you break REST principles, do it intentionally and document it clearly.

6. HTTP Methods and Semantics

HTTP methods define the action you want to perform on a resource. The most common methods are GET, POST, PUT, PATCH, and DELETE.

The Big Five

Safe vs. Idempotent

Two critical properties define how methods behave:

Safe methods (safe-methods): Don’t modify resources. You can call them repeatedly without side effects.

• ✅ GET, HEAD, OPTIONS
• ❌ POST, PUT, DELETE

Idempotent methods (idempotency): Calling them multiple times has the same effect as calling them once.

• ✅ GET, PUT, DELETE
• ❌ POST

graph TD
    A[HTTP Methods] --> B[Safe]
    A --> C[Unsafe]
    B --> D[GET, HEAD, OPTIONS]
    C --> E[Idempotent]
    C --> F[Non-Idempotent]
    E --> G[PUT, DELETE]
    F --> H[POST]
    style B fill:#c8e6c9
    style E fill:#fff9c4
    style F fill:#ffccbc

Why this matters:

• Safe methods can be cached, prefetched, and retried without risk.
• Idempotent methods can be safely retried if the network fails (did it work? Just send it again).
• Non-idempotent methods (POST) are dangerous to retry automatically.

Example: If you click “Submit Order” and the network times out, should the app retry?

• If it’s POST /orders → No, you might create two orders.
• If it’s PUT /orders/123 → Yes, retrying won’t create duplicates.

Why Misusing Methods Breaks Clients

If you use GET to delete resources:

GET /users/123?action=delete

You’ve broken HTTP semantics. Consequences:

1. Caching: Proxies cache GET requests. A cached response means the delete never happens.
2. Browser prefetching: Browsers prefetch GET links to speed up navigation. Your user’s browser might delete data just by hovering over a link.
3. Crawlers: Search engine bots follow GET links. They’ll delete all your data.

Use the right method for the right job.

7. Status Codes: The Language of Errors

HTTP status codes tell the client what happened. They’re grouped by category:

The Five Families

Why Not Everything is 200

Returning 200 OK for errors is an anti-pattern:

HTTP/1.1 200 OK

{
  "success": false,
  "error": "User not found"
}

Problems:

• HTTP proxies see 200 and think everything’s fine.
• Monitoring tools can’t detect errors.
• Clients have to parse the body to know if it worked.

Better approach:

HTTP/1.1 404 Not Found

{
  "error": "User not found",
  "code": "USER_NOT_FOUND"
}

Now the status code carries semantic meaning. Tools can detect errors without parsing JSON.

Difference Between 401 and 403

These two are often confused:

• 401 Unauthorized: You haven’t authenticated. “I don’t know who you are. Please log in.”
• 403 Forbidden: You’re authenticated, but you don’t have permission. “I know who you are, but you can’t access this.”

flowchart TD
    A[Request] --> B{Authenticated?}
    B -->|No| C[401 Unauthorized]
    B -->|Yes| D{Authorized?}
    D -->|No| E[403 Forbidden]
    D -->|Yes| F[200 OK]
    style C fill:#ffccbc
    style E fill:#ffccbc
    style F fill:#c8e6c9

Example:

• Accessing /users/123 without a token → 401
• Accessing /admin/users as a regular user → 403

Client Error vs. Server Error

4xx errors mean the client sent a bad request. It’s the client’s fault:

• 400 Bad Request: Malformed JSON, missing required fields
• 404 Not Found: Resource doesn’t exist
• 429 Too Many Requests: Rate limit exceeded

5xx errors mean the server failed to process a valid request. It’s the server’s fault:

• 500 Internal Server Error: Unhandled exception
• 502 Bad Gateway: Upstream server failed
• 503 Service Unavailable: Server is overloaded or down

Why the distinction matters: Clients should retry 5xx errors (the server might recover). They shouldn’t retry 4xx errors (the request is broken and won’t work even if retried).

8. Data: Headers, Body, and Formats

HTTP requests and responses have two places to put data: headers and body.

What Goes in Headers

Headers contain metadata about the request or response—information about the data, not the data itself.

Common request headers:

Authorization: Bearer eyJhbGci...      # Who you are
Content-Type: application/json        # Format of the body you're sending
Accept: application/json               # Format you want back
User-Agent: MyApp/1.0                  # Client information

Common response headers:

Content-Type: application/json        # Format of the body
Cache-Control: max-age=3600            # How long to cache this
X-Rate-Limit-Remaining: 99             # Custom: API rate limit info

What Goes in Body

The body contains the actual data:

Request body (POST/PUT/PATCH):

{
  "name": "Alice",
  "email": "[email protected]",
  "age": 30
}

Response body (GET):

{
  "id": 123,
  "name": "Alice",
  "email": "[email protected]",
  "createdAt": "2026-01-09T10:00:00Z"
}

JSON as Dominant Format

While HTTP supports any format (XML, CSV, HTML), JSON (JavaScript Object Notation) is the de facto standard for REST APIs.

Why JSON won:

• Human-readable
• Supported natively by JavaScript (browsers)
• Compact (smaller than XML)
• Easy to parse in every language

Example JSON response:

{
  "user": {
    "id": 123,
    "name": "Alice",
    "accounts": [
      {
        "id": 456,
        "balance": 5432.10,
        "currency": "USD"
      },
      {
        "id": 789,
        "balance": 1200.00,
        "currency": "EUR"
      }
    ]
  }
}

What Content Negotiation Is (Briefly)

Content negotiation lets clients request different formats using the Accept header:

GET /users/123
Accept: application/json        → Server returns JSON

GET /users/123
Accept: application/xml         → Server returns XML

Most modern APIs only support JSON and ignore the Accept header, but the principle is part of REST’s uniform interface.

9. What is NOT a REST API

Let’s clear up misconceptions by showing what isn’t REST.

RPC over HTTP

An API that exposes actions as endpoints:

POST /createUser
POST /deleteUser
POST /calculateInterest
POST /sendEmail

This is RPC (Remote Procedure Call) over HTTP, not REST. It’s not wrong, but it’s not REST:

• URLs are verbs, not nouns
• Everything uses POST
• You lose HTTP’s built-in semantics (caching, idempotency)

When RPC makes sense: Internal microservices, actions that don’t map to resources (e.g., /calculate-route).

APIs That Change Without Notice

A “REST API” that returns different data structures for the same endpoint:

Monday:

{
  "balance": 1234.56
}

Tuesday (breaking change):

{
  "accountBalance": "1234.56 USD"
}

Changing balance to accountBalance (or number to string) breaks every client. REST APIs must be stable and versioned. Changes must be backward-compatible or introduced in a new API version.

APIs Returning HTML or Inconsistent Errors

If your API returns HTML when there’s an error:

HTTP/1.1 500 Internal Server Error
Content-Type: text/html

<html>
  <body>
    <h1>Oops! Something went wrong.</h1>
  </body>
</html>

Your client (expecting JSON) will crash trying to parse HTML. Consistency matters. If your API returns JSON, always return JSON—even for errors.

GraphQL and gRPC: Different Paradigms

GraphQL and gRPC are not REST:

• GraphQL: Single endpoint (/graphql), clients query exactly what they need.
• gRPC: Binary protocol using Protobuf, designed for high performance between microservices.

These are valid alternatives to REST, not “better” or “worse”—just different tools for different use cases.

10. What Comes Next

You now understand the fundamentals of how REST APIs work. Here’s where to go deeper:

Future Guides (Coming Soon)

1. API Design Best Practices: How to design intuitive, scalable REST APIs
2. API Security Fundamentals: Authentication, authorization, and common vulnerabilities
3. API Versioning Strategies: How to evolve APIs without breaking clients
4. API Performance Optimization: Caching, pagination, rate limiting, and compression
5. OpenAPI and Documentation: How to document APIs with OpenAPI 3.x

Related Vocabulary Terms

Deepen your understanding by exploring these terms:

• REST - Architectural style for networked applications
• RESTful API - APIs that follow REST principles
• HTTP - The protocol that powers REST APIs
• Resource - The fundamental concept in REST
• Client-Server - Separation of concerns in distributed systems
• Stateless - Why REST APIs don’t remember previous requests
• HTTP Methods - GET, POST, PUT, DELETE, and more
• Idempotency - Why some methods are safe to retry
• Safe Methods - Methods that don’t modify resources
• HTTP Status Codes - The language of success and errors

Tools to Explore

• Postman or Insomnia: Test REST APIs interactively
• curl: Command-line tool to make HTTP requests
• Browser DevTools: Network tab to inspect API calls from web apps
• OpenAPI (Swagger): Define and document your APIs

Congratulations! You’ve built a mental model of how REST APIs work. The next step is hands-on practice: explore public APIs, build your own, and see these principles in action.