What is a REST API — Simple Explanation with Examples

A REST API (Representational State Transfer) is an architectural style for building web services that treat server data as resources accessible via standard HTTP methods. REST APIs are stateless, use uniform interfaces, and represent resources in formats like JSON or XML.

What You’ll Learn

This article covers the core REST principles, HTTP methods and status codes, URL structure patterns, and a working example. REST is the dominant API design style on the web — nearly every public API you interact with (Twitter, Stripe, GitHub) follows REST principles.

The Problem REST Solves

Before REST, web APIs used various inconsistent designs. SOAP (Simple Object Access Protocol) was common but complex: it required XML envelopes, strict WSDL contracts, and heavy tooling. Each API had its own custom approach, making integration hard.

REST introduced a uniform, resource-oriented approach:

• Use standard HTTP methods (GET, POST, PUT, DELETE) — developers already know them.
• Use URLs to identify resources — intuitive and self-documenting.
• Use standard status codes — everyone understands 404 means “Not Found.”
• Be stateless — each request contains all the information needed, simplifying scaling.

REST made APIs predictable. If you understand one REST API, you understand the general pattern of all of them.

The Library Analogy

A REST API is like a library:

• The library (server) has shelves of books (resources).
• Each book has a unique location (URL) — /non-fiction/engineering/rest-api-design.
• The librarian processes your requests according to standard rules:
  • Browse shelves = GET (retrieve resources)
  • Borrow a book = POST (create a record/action)
  • Replace a book = PUT (full update)
  • Fix a torn page = PATCH (partial update)
  • Remove a book = DELETE (delete resource)
• You do not need to know how the library organizes its back office (statelessness).
• The card catalog is the API documentation — it tells you what resources exist and how to access them.

REST Principles

1. Statelessness

Each request from client to server must contain all the information necessary to understand and process the request. The server does not store any session state between requests.

# Each request includes auth (no session reliance)
curl -H "Authorization: Bearer token123" https://api.example.com/users

2. Uniform Interface

Resources are identified in requests (URLs). Resources are manipulated through representations (JSON). Each message is self-descriptive.

3. Resource-Based

Everything is a resource: a user, an order, a product, a comment. Resources are nouns, not verbs.

4. Cacheability

Responses must define themselves as cacheable or not, improving performance and reducing server load.

HTTP Methods (CRUD)

HTTP Status Codes

URL Structure

REST URLs follow a consistent, hierarchical pattern:

GET    /users                    → List all users
GET    /users/42                 → Get user with ID 42
POST   /users                    → Create a new user
PUT    /users/42                 → Replace user 42
PATCH  /users/42                 → Partially update user 42
DELETE /users/42                 → Delete user 42

GET    /users/42/orders          → List orders for user 42
POST   /users/42/orders          → Create an order for user 42
GET    /users/42/orders/7        → Get order 7 for user 42

GET    /products?category=books&sort=price_asc   → Filtered & sorted list

Example: REST API with cURL

Let’s interact with a RESTful JSON API (JSONPlaceholder, a fake API for testing):

GET — Retrieve Posts

curl -X GET "https://jsonplaceholder.typicode.com/posts/1" \
  -H "Accept: application/json"

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit..."
}

POST — Create a Post

curl -X POST "https://jsonplaceholder.typicode.com/posts" \
  -H "Content-Type: application/json" \
  -d '{"title": "My New Post", "body": "This is the content.", "userId": 1}'

{
  "title": "My New Post",
  "body": "This is the content.",
  "userId": 1,
  "id": 101
}

PUT — Replace a Post

curl -X PUT "https://jsonplaceholder.typicode.com/posts/1" \
  -H "Content-Type: application/json" \
  -d '{"id": 1, "title": "Updated Title", "body": "Updated body", "userId": 1}'

DELETE — Remove a Post

curl -X DELETE "https://jsonplaceholder.typicode.com/posts/1"
# Response: 200 OK with empty body (or 204 No Content)

REST vs SOAP

Common Use Cases

1. Public web APIs — GitHub API, Stripe API, Twilio API, Twitter API — all follow RESTful conventions for third-party integrations.

2. Mobile backends — Mobile apps communicate with backend servers via REST APIs, sending JSON and receiving JSON responses.

3. Microservice communication — Internal services expose REST endpoints for synchronous communication within a service mesh.

4. Single-page applications — React, Vue, and Angular apps fetch and mutate data from REST backends using fetch or Axios.

5. IoT device control — IoT devices expose REST endpoints for reading sensor data and issuing commands.

FAQ

Related Terms

What is an API — What is GraphQL — What is a JWT — What is OAuth 2.0