What is REST API? Complete Guide for Developers

┌─────────────┐                      ┌─────────────┐
│   Client    │  ──── Request ────▶  │   Server    │
│  (Your App) │                      │  (Backend)  │
│             │  ◀─── Response ────  │             │
└─────────────┘                      └─────────────┘

┌─────────────┐         ┌─────────────┐
│   Client    │◀───────▶│   Server    │
│  (React UI) │   HTTP  │  (Node.js)  │
└─────────────┘         └─────────────┘
       ▲                       ▲
       │                       │
   UI Logic              Business Logic
   Presentation          Data Storage

// ❌ Stateful (server remembers user)
GET /api/cart  // Server: "Which user? I need to check session..."
 
// ✅ Stateless (request contains everything)
GET /api/users/123/cart
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

HTTP/1.1 200 OK
Cache-Control: max-age=3600, public
ETag: "abc123"
 
{
  "products": [...]
}

Client → CDN → Load Balancer → API Gateway → Server

Resource: User #123
URI: /api/users/123
Representation (JSON):
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com"
}

# Get a single user
GET /api/users/123 HTTP/1.1
Host: api.example.com
Accept: application/json
 
# Response
HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "createdAt": "2024-01-15T10:30:00Z"
}

# Get a collection with filtering and pagination
GET /api/users?role=admin&page=1&limit=10 HTTP/1.1
 
# Response
HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "data": [
    {"id": 1, "name": "Alice", "role": "admin"},
    {"id": 2, "name": "Bob", "role": "admin"}
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "totalPages": 1
  }
}

# Create a new user
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
 
{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "password": "securepassword123"
}
 
# Response
HTTP/1.1 201 Created
Location: /api/users/124
Content-Type: application/json
 
{
  "id": 124,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "createdAt": "2024-01-20T14:22:00Z"
}

# Replace user 123 entirely
PUT /api/users/123 HTTP/1.1
Content-Type: application/json
 
{
  "name": "John Smith",
  "email": "john.smith@example.com",
  "role": "admin"
}
 
# Response
HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "id": 123,
  "name": "John Smith",
  "email": "john.smith@example.com",
  "role": "admin",
  "updatedAt": "2024-01-20T15:00:00Z"
}

# Update only the email
PATCH /api/users/123 HTTP/1.1
Content-Type: application/json
 
{
  "email": "newemail@example.com"
}
 
# Response
HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "id": 123,
  "name": "John Smith",
  "email": "newemail@example.com",
  "role": "admin",
  "updatedAt": "2024-01-20T15:30:00Z"
}

// PUT: Must include ALL fields
PUT /api/users/123
{
  "name": "John",
  "email": "john@example.com",
  "role": "user",
  "phone": null,
  "address": null
}
 
// PATCH: Only include what changes
PATCH /api/users/123
{
  "role": "admin"
}

# Delete user 123
DELETE /api/users/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
 
# Response options:
 
# Option 1: 204 No Content (preferred)
HTTP/1.1 204 No Content
 
# Option 2: 200 OK with deleted resource
HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "id": 123,
  "name": "John Smith",
  "deleted": true,
  "deletedAt": "2024-01-20T16:00:00Z"
}

# Check if resource exists
HEAD /api/users/123 HTTP/1.1
 
# Response
HTTP/1.1 200 OK
Content-Length: 256
Last-Modified: Sat, 20 Jan 2024 15:30:00 GMT
ETag: "abc123"

# What methods are allowed?
OPTIONS /api/users HTTP/1.1
 
# Response
HTTP/1.1 200 OK
Allow: GET, POST, HEAD, OPTIONS
Access-Control-Allow-Methods: GET, POST, PUT, DELETE

# 200 OK - Resource retrieved
GET /api/users/123
→ 200 OK with user data
 
# 201 Created - New resource created
POST /api/users
→ 201 Created with new user + Location header
 
# 202 Accepted - Async job started
POST /api/reports/generate
→ 202 Accepted with job ID
 
# 204 No Content - Deleted successfully
DELETE /api/users/123
→ 204 No Content

# 301 Moved Permanently
GET /api/v1/users
→ 301 Moved Permanently
   Location: /api/v2/users
 
# 304 Not Modified (caching)
GET /api/users/123
If-None-Match: "abc123"
→ 304 Not Modified

# 400 Bad Request - Malformed JSON
POST /api/users
Content-Type: application/json
{ "name": "John", }  ← trailing comma
 
→ 400 Bad Request
{
  "error": "Bad Request",
  "message": "Invalid JSON in request body"
}
 
# 401 Unauthorized - Missing or invalid token
GET /api/users/123
Authorization: Bearer invalid_token
 
→ 401 Unauthorized
{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}
 
# 403 Forbidden - User can't access resource
DELETE /api/users/1  ← Admin trying to delete super admin
 
→ 403 Forbidden
{
  "error": "Forbidden",
  "message": "Cannot delete super admin users"
}
 
# 404 Not Found - Resource doesn't exist
GET /api/users/99999
 
→ 404 Not Found
{
  "error": "Not Found",
  "message": "User with id 99999 not found"
}
 
# 409 Conflict - State conflict
POST /api/users
{ "email": "existing@example.com" }
 
→ 409 Conflict
{
  "error": "Conflict",
  "message": "User with this email already exists"
}
 
# 422 Unprocessable Entity - Validation failed
POST /api/users
{ "email": "not-an-email", "age": -5 }
 
→ 422 Unprocessable Entity
{
  "error": "Validation Error",
  "details": [
    {"field": "email", "message": "Invalid email format"},
    {"field": "age", "message": "Age must be positive"}
  ]
}
 
# 429 Too Many Requests - Rate limited
GET /api/users
 
→ 429 Too Many Requests
Retry-After: 60
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 60 seconds"
}

# 500 Internal Server Error - Catch-all for bugs
GET /api/users
 
→ 500 Internal Server Error
{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred",
  "requestId": "req_abc123"  ← for debugging
}
 
# 503 Service Unavailable - Planned maintenance
GET /api/users
 
→ 503 Service Unavailable
Retry-After: 3600
{
  "error": "Service Unavailable",
  "message": "Scheduled maintenance in progress"
}

Request received
├── Is the request valid?
│   ├── No → 400 Bad Request
│   └── Yes ↓
├── Is authentication required?
│   ├── Yes, and missing/invalid → 401 Unauthorized
│   └── Has valid auth ↓
├── Is user authorized for this action?
│   ├── No → 403 Forbidden
│   └── Yes ↓
├── Does the resource exist?
│   ├── No → 404 Not Found
│   └── Yes ↓
├── Is the method allowed?
│   ├── No → 405 Method Not Allowed
│   └── Yes ↓
├── Is there a conflict?
│   ├── Yes → 409 Conflict
│   └── No ↓
├── Is the data valid?
│   ├── No → 422 Unprocessable Entity
│   └── Yes ↓
├── Did the server crash?
│   ├── Yes → 500 Internal Server Error
│   └── No ↓
└── Success! → 2xx (200, 201, 204)

https://api.example.com/v1/users/123/orders?status=pending&limit=10
└─┬─┘   └─────┬─────┘ └┬┘ └────┬─────────┘ └────────┬───────────┘
scheme      host    version  path (resource)    query params

✅ Good (nouns)
GET /users
POST /orders
DELETE /products/123
 
❌ Bad (verbs)
GET /getUsers
POST /createOrder
DELETE /deleteProduct/123

✅ Good (plural)
/users
/users/123
/products
/products/456/reviews
 
❌ Bad (inconsistent)
/user          ← singular
/users/123     ← plural
/product/456

✅ Good
/user-profiles
/order-items
/blog-posts
 
❌ Bad
/user_profiles     ← underscores
/userprofiles      ← no separator
/UserProfiles      ← PascalCase

✅ Good
/users/123/orders
 
❌ Bad
/Users/123/Orders
/USERS/123/ORDERS

# User's orders
GET /users/123/orders
 
# Order's items
GET /orders/456/items
 
# Specific item in an order
GET /orders/456/items/789

❌ Too deep
/users/123/orders/456/items/789/variants/321
 
✅ Better - flatten when needed
/order-items/789?include=variants

GET /products?category=electronics&price_min=100&price_max=500
GET /users?role=admin&status=active
GET /orders?created_after=2024-01-01

GET /products?sort=price         # ascending
GET /products?sort=-price        # descending (prefix with -)
GET /products?sort=category,-price  # multiple fields

# Offset-based
GET /products?page=2&limit=20
 
# Cursor-based
GET /products?cursor=abc123&limit=20

GET /users?fields=id,name,email
GET /users/123?fields=name,avatar

GET /orders/123?include=items,customer
GET /posts?include=author,comments

# Actions on resources
POST /users/123/activate
POST /orders/456/cancel
POST /payments/789/refund
 
# Search across resources
GET /search?q=laptop&type=products,reviews
 
# Aggregations
GET /stats/users/monthly
GET /reports/sales?year=2024

// Creating a user
POST /api/users
Content-Type: application/json
 
{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "securePass123!",
  "profile": {
    "bio": "Software developer",
    "location": "San Francisco",
    "website": "https://johndoe.dev"
  },
  "preferences": {
    "newsletter": true,
    "theme": "dark"
  }
}

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "profile": {
    "bio": "Software developer",
    "location": "San Francisco"
  },
  "createdAt": "2024-01-20T14:30:00Z",
  "updatedAt": "2024-01-20T14:30:00Z"
}

{
  "data": [
    {"id": 1, "name": "John"},
    {"id": 2, "name": "Jane"},
    {"id": 3, "name": "Bob"}
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 10,
    "totalPages": 15
  },
  "links": {
    "self": "/api/users?page=1&limit=10",
    "next": "/api/users?page=2&limit=10",
    "last": "/api/users?page=15&limit=10"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "value": "not-an-email"
      },
      {
        "field": "password",
        "message": "Must be at least 8 characters",
        "value": "short"
      }
    ],
    "timestamp": "2024-01-20T15:00:00Z",
    "requestId": "req_abc123xyz"
  }
}

{
  "createdAt": "2024-01-20T14:30:00Z",        // UTC
  "scheduledFor": "2024-01-25T09:00:00-08:00", // With offset
  "date": "2024-01-20"                         // Date only
}

# In header
GET /api/data HTTP/1.1
X-API-Key: sk_live_abc123xyz
 
# Or in query (less secure)
GET /api/data?api_key=sk_live_abc123xyz

GET /api/users/me HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4iLCJpYXQiOjE1MTYyMzkwMjJ9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

header.payload.signature

// Decoded payload
{
  "sub": "user_123",
  "name": "John Doe",
  "role": "admin",
  "iat": 1516239022,
  "exp": 1516325422
}

# Step 1: Redirect to authorization server
GET https://accounts.google.com/oauth/authorize?
  client_id=your-client-id&
  redirect_uri=https://yourapp.com/callback&
  scope=email profile&
  response_type=code
 
# Step 2: Exchange code for token
POST https://oauth2.googleapis.com/token
{
  "code": "auth_code_from_callback",
  "client_id": "your-client-id",
  "client_secret": "your-secret",
  "grant_type": "authorization_code"
}
 
# Step 3: Use access token
GET /api/users/me HTTP/1.1
Authorization: Bearer access_token_from_step_2

// User with roles
{
  "id": 123,
  "email": "admin@example.com",
  "roles": ["admin", "editor"]
}
 
// Permission check
if (user.roles.includes("admin")) {
  // Allow action
}

// User with specific permissions
{
  "id": 123,
  "permissions": [
    "users:read",
    "users:write",
    "posts:read",
    "posts:write",
    "posts:delete"
  ]
}

# Response headers
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Security-Policy: default-src 'self'

GET /api/v1/users
GET /api/v2/users

GET /api/users HTTP/1.1
Accept-Version: v2
 
# or
API-Version: 2024-01-20

GET /api/users?version=2

GET /api/users HTTP/1.1
Accept: application/vnd.company.v2+json

GET /api/users?page=2&limit=20

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": true
  }
}

GET /api/users?cursor=eyJpZCI6MTIzfQ&limit=20

{
  "data": [...],
  "cursors": {
    "before": "eyJpZCI6MTAzfQ",
    "after": "eyJpZCI6MTIzfQ",
    "hasMore": true
  }
}

# First page
GET /api/users?limit=20
 
# Next page (after last item's created_at)
GET /api/users?created_after=2024-01-20T14:30:00Z&limit=20

GET /api/products?category=electronics&brand=apple

GET /api/products?price_min=100&price_max=500
GET /api/orders?created_after=2024-01-01&created_before=2024-02-01

GET /api/products?filter={"category":"electronics","price":{"$gte":100,"$lte":500}}

GET /api/products?sort=price          # Ascending
GET /api/products?sort=-price         # Descending (prefix with -)

GET /api/products?sort=-featured,price   # Featured first, then by price

GET /api/products?q=wireless+headphones

GET /api/search?q=laptop&fields=name,description&fuzzy=true

GET /api/products?
  category=electronics&
  price_min=100&
  price_max=1000&
  sort=-rating,price&
  q=laptop&
  page=1&
  limit=20&
  fields=id,name,price,rating

{
  "id": 123,
  "status": "pending",
  "total": 99.99
}

{
  "id": 123,
  "status": "pending",
  "total": 99.99,
  "_links": {
    "self": {"href": "/api/orders/123"},
    "items": {"href": "/api/orders/123/items"},
    "customer": {"href": "/api/customers/456"},
    "cancel": {
      "href": "/api/orders/123/cancel",
      "method": "POST"
    },
    "payment": {
      "href": "/api/orders/123/payment",
      "method": "POST"
    }
  }
}

{
  "id": 123,
  "_links": {
    "self": {"href": "/orders/123"},
    "items": {"href": "/orders/123/items"}
  },
  "_embedded": {
    "items": [
      {"id": 1, "name": "Product A"}
    ]
  }
}

{
  "data": {
    "type": "orders",
    "id": "123",
    "attributes": {"status": "pending"},
    "relationships": {
      "items": {
        "links": {
          "related": "/orders/123/items"
        }
      }
    }
  }
}

✅ GET for reading
✅ POST for creating
✅ PUT/PATCH for updating
✅ DELETE for deleting
 
❌ POST /deleteUser
❌ GET /createUser?name=John

✅ 200 for successful GET/PUT/PATCH
✅ 201 for successful POST (creation)
✅ 204 for successful DELETE
✅ 400 for bad client input
✅ 401 for authentication failure
✅ 403 for authorization failure
✅ 404 for missing resources
✅ 500 for server errors
 
❌ 200 for everything with "error" in body

✅ /users (plural, lowercase)
✅ /user-profiles (hyphenated)
✅ /orders/123/items (nested resources)
 
❌ /User
❌ /user_profile
❌ /getOrders

✅ /api/v1/users
✅ /api/v2/users
 
❌ /api/users (no version = trouble later)

// ✅ Good: Structured error with details
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {"field": "email", "message": "Invalid email format"}
    ]
  }
}
 
// ❌ Bad: Generic error message
{
  "error": "Something went wrong"
}

✅ https://api.example.com
❌ http://api.example.com

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200
Retry-After: 60
 
{
  "error": "Rate limit exceeded"
}

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List all users
      responses:
        '200':
          description: Successful response

# Request
Accept: application/json
 
# Response
Content-Type: application/json

HTTP/1.1 500 Internal Server Error
X-Request-ID: req_abc123xyz
 
{
  "error": "Internal server error",
  "requestId": "req_abc123xyz"
}

GET /api/posts
POST /api/posts
GET /api/posts/:id
PUT /api/posts/:id
DELETE /api/posts/:id
GET /api/posts/:id/comments
POST /api/posts/:id/comments
GET /api/users/:id/posts

GET /api/todos         - List all todos
POST /api/todos        - Create a todo
GET /api/todos/:id     - Get a todo
PATCH /api/todos/:id   - Update a todo
DELETE /api/todos/:id  - Delete a todo