REST API

What is a REST API?

A REST API (Representational State Transfer Application Programming Interface) is a web service that follows the REST architectural style, defined by Roy Fielding in his 2000 doctoral dissertation. REST APIs use standard HTTP methods to perform operations on resources identified by URIs (Uniform Resource Identifiers), returning data in formats like JSON or XML.

REST has become the dominant architectural style for web APIs, powering everything from social media platforms to AI model serving endpoints. Its simplicity, scalability, and compatibility with HTTP make it the first choice for most web service implementations.

The 6 REST Constraints

Roy Fielding defined six architectural constraints that a system must satisfy to be considered RESTful. These constraints work together to create scalable, maintainable, and performant APIs.

HTTP Methods & CRUD Operations

REST APIs map standard HTTP methods to CRUD (Create, Read, Update, Delete) operations. Each method has specific semantics regarding safety and idempotency.

HTTP Status Codes

REST APIs communicate the result of each request through standardized HTTP status codes, grouped into five classes.

Resource Design & URL Patterns

Well-designed REST APIs follow consistent naming conventions for resources and endpoints. URIs should be intuitive, hierarchical, and use nouns (not verbs).

# Good: Use nouns (resources)
GET    /api/v1/users              # List users
GET    /api/v1/users/42           # Get user 42
POST   /api/v1/users              # Create user
PUT    /api/v1/users/42           # Update user 42
DELETE /api/v1/users/42           # Delete user 42

# Nested resources (relationships)
GET    /api/v1/users/42/posts     # Posts by user 42
GET    /api/v1/users/42/posts/7   # Post 7 of user 42

# Filtering, sorting, pagination
GET    /api/v1/users?role=admin&sort=name&page=2&limit=20

# Bad: Avoid verbs in URLs
GET    /api/v1/getUser/42         # Don't do this
POST   /api/v1/createUser         # Don't do this
POST   /api/v1/deleteUser/42      # Don't do this

Request & Response Examples

POST /api/v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...

{
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "role": "developer"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/143

{
    "id": 143,
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "role": "developer",
    "created_at": "2025-01-28T10:30:00Z",
    "_links": {
        "self": "/api/v1/users/143",
        "posts": "/api/v1/users/143/posts"
    }
}

{
    "data": [
        {"id": 1, "name": "Alice", "role": "developer"},
        {"id": 2, "name": "Bob", "role": "designer"}
    ],
    "pagination": {
        "page": 1,
        "per_page": 20,
        "total": 142,
        "total_pages": 8
    },
    "_links": {
        "self": "/api/v1/users?page=1",
        "next": "/api/v1/users?page=2",
        "last": "/api/v1/users?page=8"
    }
}

Authentication & Security

Since REST is stateless, each request must carry its own authentication credentials. Common patterns include:

Authorization: Api-Key sk-abc123...
# or
GET /api/data?api_key=sk-abc123...

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

POST /oauth/token
grant_type=client_credentials
&client_id=...&client_secret=...

Authorization: Basic dXNlcjpwYXNz...

REST APIs in AI & GenAI

REST APIs are the primary interface for consuming AI and GenAI services. From OpenAI to Anthropic, every major AI provider exposes their models through REST endpoints.

POST /v1/chat/completions
{
  "model": "gpt-4",
  "messages": [
    {"role": "user",
     "content": "Explain REST"}
  ],
  "temperature": 0.7
}

POST /v1/embeddings
{
  "model": "text-embedding-3-large",
  "input": "REST API design"
}

// Response: 3072-dim vector
{"data": [{"embedding": [0.023, ...]}]}

Building a REST API (Python)

from fastapi import FastAPI, HTTPException, Query
from pydantic import BaseModel, EmailStr
from typing import Optional

app = FastAPI(title="Users API", version="1.0")

# Models
class UserCreate(BaseModel):
    name: str
    email: EmailStr
    role: str = "user"

class UserResponse(BaseModel):
    id: int
    name: str
    email: str
    role: str

# Endpoints
@app.get("/api/v1/users", response_model=list[UserResponse])
async def list_users(
    page: int = Query(1, ge=1),
    limit: int = Query(20, le=100)
):
    return get_users(page=page, limit=limit)

@app.post("/api/v1/users", response_model=UserResponse, status_code=201)
async def create_user(user: UserCreate):
    return save_user(user)

@app.get("/api/v1/users/{user_id}", response_model=UserResponse)
async def get_user(user_id: int):
    user = find_user(user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return user

@app.delete("/api/v1/users/{user_id}", status_code=204)
async def delete_user(user_id: int):
    delete_user_by_id(user_id)

import requests
import httpx  # async alternative

# Sync with requests
response = requests.get(
    "https://api.example.com/v1/users",
    headers={"Authorization": "Bearer token..."},
    params={"page": 1, "limit": 20}
)
users = response.json()

# Async with httpx
async with httpx.AsyncClient() as client:
    response = await client.post(
        "https://api.example.com/v1/users",
        json={"name": "Alice", "email": "alice@ex.com"},
        headers={"Authorization": "Bearer token..."}
    )
    new_user = response.json()

REST vs Alternatives

Error Handling Best Practices

Consistent error responses make APIs easier to consume and debug. Follow a standard error format across all endpoints.

HTTP/1.1 422 Unprocessable Entity

{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Invalid request data",
        "details": [
            {
                "field": "email",
                "message": "Must be a valid email address",
                "value": "not-an-email"
            }
        ],
        "request_id": "req_abc123",
        "docs": "https://docs.api.com/errors#VALIDATION_ERROR"
    }
}

Best Practices

• Use nouns for resources, HTTP methods for actions: GET /users not GET /getUsers. Let the HTTP method convey the action.
• Version your API from day one: Use URL versioning (/v1/) or header-based versioning to allow backward-compatible evolution.
• Implement pagination for lists: Never return unbounded results. Use page/limit or cursor-based pagination for large datasets.
• Return appropriate status codes: Don't always return 200. Use 201 for creation, 204 for deletion, 404 for not found, 422 for validation errors.
• Use consistent error format: Include error code, message, details, and request_id in every error response for debuggability.
• Add rate limiting and throttling: Protect your API from abuse. Return 429 Too Many Requests with Retry-After header.
• Document with OpenAPI/Swagger: Use auto-generated docs (FastAPI does this natively) or hand-crafted OpenAPI specs.

Documentation & Testing Tools

Learn More

Related Topics