REST API Design — Backend & Servers

REST (Representational State Transfer) is an architectural style for providing standards between computer systems on the web. Good API design makes your systems predictable, easy to consume, and highly scalable. In this guide, we'll build APIs the way industry leaders do.

Step 1 — Resource Naming Conventions

REST APIs are designed around resources (nouns), not actions (verbs). URLs should identify the entity you are interacting with.

Golden Rules for Endpoints

Use nouns, not verbs: /users not /getUsers
Use plural nouns: /users not /user
Use kebab-case for multiple words: /user-profiles not /user_profiles or /userProfiles
Keep URLs hierarchy logical: /users/123/orders (Orders belonging to User 123)

❌ BAD:
GET  /getAllUsers
POST /createUser
GET  /articles/author/123/getDrafts

✅ GOOD:
GET  /users
POST /users
GET  /users/123/articles?state=draft

Step 2 — HTTP Methods (Verbs)

While the URL defines the resource, the HTTP method defines the action to perform on that resource.

GET    /users         // Retrieve a list of users (Read)
GET    /users/12      // Retrieve user ID 12 (Read)
POST   /users         // Create a new user (Create)
PUT    /users/12      // Completely replace user ID 12 (Update)
PATCH  /users/12      // Partially update user ID 12 (Update)
DELETE /users/12      // Delete user ID 12 (Delete)

Step 3 — HTTP Status Codes

APIs should use standard HTTP status codes to communicate the result of a client's request.

Essential Status Codes

200 OK: Request succeeded (used for GET, PUT, PATCH).
201 Created: Resource was successfully created (used for POST).
204 No Content: Request succeeded but no data returned (often used for DELETE).
400 Bad Request: The client sent invalid data (e.g., missing required fields).
401 Unauthorized: Authentication is missing or invalid (client must log in).
403 Forbidden: Authenticated, but lacks permission to perform the action.
404 Not Found: The requested resource does not exist.
429 Too Many Requests: Rate limit exceeded.
500 Internal Server Error: The server crashed. The client did nothing wrong.

Step 4 — Filtering, Sorting, and Pagination

Never return thousands of records at once. Always paginate collections and use query parameters for filtering and sorting.

GET /users?role=admin&status=active      // Filtering
GET /users?sort=-created_at              // Sorting (minus means descending)
GET /users?fields=id,name,email          // Sparse Fieldsets (return only specific fields)
GET /users?page=2&limit=50               // Offset Pagination
GET /users?cursor=eyJpZCI6MTIzfQ&limit=5 // Cursor Pagination

Step 5 — Error Handling & Responses

Provide standardized, actionable error payloads. The RFC 7807 (Problem Details for HTTP APIs) is a great standard to follow.

{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Your request parameters didn't validate.",
  "status": 400,
  "detail": "The 'password' field must be at least 8 characters.",
  "instance": "/users",
  "errors": [
    {
      "field": "password",
      "message": "Must be at least 8 characters"
    }
  ]
}

Step 6 — API Versioning

When you make breaking changes (removing a field, changing data types), you must version your API so existing mobile apps and integrations don't break.

Versioning Strategies

URI Versioning (Most Common): /api/v1/users and /api/v2/users
Header Versioning (Cleaner): Sending an Accept-Version: v1 header.
Query Param Versioning: /api/users?version=1 (Not recommended)

Step 7 — Security Best Practices

An API exposed to the internet is a prime target for attacks. Ensure these basics are covered.

Always use HTTPS (TLS) — never serve API traffic over plaintext HTTP.
Use stateless authentication (e.g. JWT) or secure, HTTP-only, SameSite cookies.
Implement Rate Limiting to prevent DoS attacks and brute-forcing.
Validate all input strictly. Never trust client data to prevent SQL Injection and XSS.
Do not leak sensitive data in URLs (use POST bodies instead) as URLs are logged in server logs.