REST API
CHEAT SHEET.

What is REST?

• REpresentational State Transfer
• Architectural style for designing networked applications
• Uses HTTP as the protocol
• Stateless – each request contains all necessary information
• Resources identified by URLs (Uniform Resource Locators)

REST Constraints

• Client‑Server – separation of concerns
• Stateless – no client context stored on server
• Cacheable – responses can be cached
• Uniform Interface – consistent API design
• Layered System – intermediaries (load balancers, proxies)
• Code on Demand – optional, executable code

HTTP Methods

When to Use Each

• GET – read data, no side effects (search, list, retrieve)
• POST – create new resource (orders, users, posts)
• PUT – full update (replace entire resource)
• PATCH – partial update (modify specific fields)
• DELETE – remove resource

HTTP Status Codes

Status Code Quick Reference

• 2xx – Everything worked
• 4xx – Client messed up
• 5xx – Server messed up

Resource Naming Conventions

Actions as Resources

// For operations that don't map to CRUD
POST /users/123/activate
POST /users/123/deactivate
POST /orders/456/submit

Request & Response Formats

JSON Example

// Request
POST /api/users
Content-Type: application/json
{
    "name": "Alice",
    "email": "alice@example.com",
    "age": 25
}

// Response
HTTP/1.1 201 Created
Content-Type: application/json
{
    "id": 123,
    "name": "Alice",
    "email": "alice@example.com",
    "age": 25,
    "createdAt": "2024-01-15T10:30:00Z"
}

Query Parameters

GET /api/users?page=2&limit=10&sort=name&order=asc
GET /api/users?name=Alice
GET /api/users?age_gte=18&age_lte=30

Pagination

// Response with pagination metadata
{
    "data": [ ... ],
    "pagination": {
        "page": 2,
        "limit": 10,
        "total": 56,
        "pages": 6,
        "next": "/api/users?page=3&limit=10",
        "prev": "/api/users?page=1&limit=10"
    }
}

// Alternative: Link headers
Link: </api/users?page=3&limit=10>; rel="next",
      </api/users?page=1&limit=10>; rel="prev"

Filtering & Sorting

GET /api/users?filter=active&sort=-createdAt
GET /api/users?fields=name,email
GET /api/users?include=posts,comments

Authentication & Authorization

GET /api/users
X-API-Key: abc123xyz

// Or in query
GET /api/users?api_key=abc123xyz

GET /api/users
Authorization: Basic dXNlcjpwYXNz

GET /api/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

GET /api/users
Authorization: Bearer // access token

// Refresh token
POST /oauth/refresh
{
    "refresh_token": "abc..."
}

JWT Structure

// Header
{
    "alg": "HS256",
    "typ": "JWT"
}

// Payload
{
    "sub": "1234567890",
    "name": "Alice",
    "iat": 1516239022,
    "exp": 1516242622
}

// Signature
HMACSHA256(
    base64UrlEncode(header) + "." + base64UrlEncode(payload),
    secret
)

Versioning

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

GET /api/users
Accept-Version: v1

GET /api/users?version=1

GET /api/users
Accept: application/vnd.myapp.v1+json

API Design Best Practices

• Use HTTPS – encrypt all traffic
• Version your API – from day one
• Use nouns for resources – not verbs
• Use plural endpoints – /users not /user
• Use proper HTTP status codes – don't return 200 for errors
• Provide consistent error responses
• Pagination, filtering, sorting – support from day one
• Limit request size – prevent abuse
• Rate limiting – protect your service
• Document your API – OpenAPI (Swagger), Postman
• Use JSON – as the primary format
• Return relevant status codes – 201 for created, 204 for no content
• Use nested resources – for relationships
• Use query parameters – for filtering, sorting, pagination
• Include proper CORS headers – for browser clients
• Log requests – for debugging and monitoring
• Use ETags – for caching and concurrency
• Use Last-Modified – for caching

Error Response Format

{
    "error": {
        "code": "INVALID_INPUT",
        "message": "The email address is not valid",
        "details": {
            "field": "email",
            "value": "invalid-email",
            "reason": "Must be a valid email format"
        },
        "timestamp": "2024-01-15T10:30:00Z",
        "path": "/api/users"
    }
}

Success Response Format

{
    "data": { ... },
    "meta": {
        "timestamp": "2024-01-15T10:30:00Z",
        "version": "v1"
    }
}

CORS Headers

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 86400

Documentation (OpenAPI 3.0)

// openapi.yaml
openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Common API Patterns

// Create
POST /users
// Read (list)
GET /users
// Read (single)
GET /users/123
// Update
PUT /users/123
// Delete
DELETE /users/123

POST /users/bulk
{
    "data": [ ... ]
}

POST /users/bulk/delete
{
    "ids": [1, 2, 3]
}

GET /users?q=alice
POST /users/search
{
    "name": "Alice",
    "age_min": 18
}

GET /health
GET /status
GET /ping