REST API Design

What is REST?

REST (Representational State Transfer) is an architectural style for designing web APIs. Think of it as a set of rules for how systems should communicate over HTTP.

Simple Analogy

Think of REST like a library:

• Resources = Books (identified by ISBN/URL)
• GET = “Show me this book”
• POST = “Add a new book”
• PUT = “Replace this entire book”
• DELETE = “Remove this book”

The librarian (server) doesn’t remember who you are (stateless) - each request is independent.

REST Principles

1. Stateless - Each request contains all information needed
2. Resource-Based - Everything is a resource (noun)
3. HTTP Methods - Use standard HTTP verbs (GET, POST, etc.)
4. Uniform Interface - Consistent way to interact with resources
5. Cacheable - Responses can be cached
6. Client-Server - Separation of concerns

---

Resources: The Foundation

Resources are the core of REST. A resource is anything that can be identified and manipulated.

What Makes a Good Resource?

Good resources are:

• ✅ Nouns, not verbs (/users, not /getUsers)
• ✅ Hierarchical (/users/123/orders)
• ✅ Plural for collections (/users, not /user)
• ✅ Consistent naming conventions

Resource Naming Examples

✅ Good	❌ Bad	Why?
/users	/getUsers	Verbs in URL
/users/123	/user/123	Inconsistent plural
/users/123/orders	/orders?userId=123	Better hierarchy
/products/456	/product?id=456	Resource in path, not query

---

HTTP Methods: The Verbs

HTTP methods define what action to perform on a resource.

CRUD Operations Mapping

Operation	HTTP Method	Idempotent?	Safe?	Use Case
Create	POST	❌ No	❌ No	Create new resource
Read	GET	✅ Yes	✅ Yes	Retrieve resource
Update (Full)	PUT	✅ Yes	❌ No	Replace entire resource
Update (Partial)	PATCH	❌ No*	❌ No	Update part of resource
Delete	DELETE	✅ Yes	❌ No	Remove resource

*PATCH can be idempotent if designed correctly

GET - Retrieve Resources

GET is for reading data. It’s safe (no side effects) and idempotent.

GET /users/123
GET /users?status=active&page=1
GET /users/123/orders

Characteristics:

• ✅ No request body (usually)
• ✅ Can be cached
• ✅ Should not modify data
• ✅ Idempotent (safe to retry)

POST - Create Resources

POST is for creating new resources. It’s not idempotent (calling twice creates two resources).

POST /users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "[email protected]"
}

Characteristics:

• ❌ Not idempotent (creates new resource each time)
• ❌ Not safe (modifies server state)
• ✅ Returns 201 Created with Location header
• ✅ Request body contains data

Response:

HTTP/1.1 201 Created
Location: /users/456
Content-Type: application/json

{
  "id": 456,
  "name": "John Doe",
  "email": "[email protected]"
}

PUT - Replace Resources

PUT replaces an entire resource. It’s idempotent (calling twice has same effect as once).

PUT /users/123
Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "[email protected]",
  "status": "active"
}

Characteristics:

• ✅ Idempotent (same result if called multiple times)
• ✅ Creates resource if it doesn’t exist (some APIs)
• ✅ Replaces entire resource
• ✅ Use when you have full resource data

PUT vs PATCH

PUT replaces the entire resource. If you send {"name": "Jane"}, it might delete other fields! Use PATCH for partial updates.

PATCH - Partial Updates

PATCH updates part of a resource. Should be idempotent if designed correctly.

PATCH /users/123
Content-Type: application/json

{
  "name": "Jane Doe"
}

Characteristics:

• ⚠️ Can be idempotent (should be designed that way)
• ✅ Only updates specified fields
• ✅ More efficient than PUT (less data)
• ✅ Use when you have partial data

DELETE - Remove Resources

DELETE removes a resource. It’s idempotent (deleting twice = same as once).

DELETE /users/123

Characteristics:

• ✅ Idempotent (deleting non-existent = same result)
• ✅ Usually returns 204 No Content
• ✅ Can return 404 if already deleted (still idempotent)

---

HTTP Status Codes

Status codes communicate the result of the request. Use them correctly!

Success Codes (2xx)

Code	Meaning	Use Case
200 OK	Request succeeded	GET, PUT, PATCH
201 Created	Resource created	POST (with Location header)
204 No Content	Success, no body	DELETE, PUT (sometimes)

Client Error Codes (4xx)

Code	Meaning	Use Case
400 Bad Request	Invalid request	Malformed JSON, missing fields
401 Unauthorized	Not authenticated	Missing/invalid token
403 Forbidden	Not authorized	Valid token, but no permission
404 Not Found	Resource doesn’t exist	Invalid ID, wrong URL
409 Conflict	Resource conflict	Duplicate email, version conflict
429 Too Many Requests	Rate limited	Too many requests

Server Error Codes (5xx)

Code	Meaning	Use Case
500 Internal Server Error	Server error	Unexpected exception
502 Bad Gateway	Upstream error	Downstream service failed
503 Service Unavailable	Service down	Maintenance, overloaded

Status Code Best Practices

✅ Do:

• Use 201 for successful creation
• Use 204 for successful deletion
• Use 400 for client errors (bad input)
• Use 404 for not found
• Use 409 for conflicts

❌ Don’t:

• Return 200 for errors (use 4xx/5xx)
• Return 500 for client errors (use 4xx)
• Return 200 for creation (use 201)

---

API Versioning Strategies

Versioning allows you to evolve your API without breaking existing clients.

Strategy 1: URL Versioning (Most Common)

Version in the URL path:

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

Pros:

• ✅ Explicit and clear
• ✅ Easy to route
• ✅ Cacheable
• ✅ Most common approach

Cons:

• ❌ URLs change
• ❌ More maintenance

Strategy 2: Header Versioning

Version in HTTP headers:

GET /users
Accept: application/vnd.api+json;version=1

Pros:

• ✅ Clean URLs
• ✅ No URL changes

Cons:

• ❌ Less discoverable
• ❌ Harder to cache
• ❌ More complex

Strategy 3: Query Parameter Versioning

Version as query parameter:

/api/users?version=1

Pros:

• ✅ Simple
• ✅ Optional

Cons:

• ❌ Easy to forget
• ❌ Not RESTful (version isn’t a resource property)

Recommendation

Use URL versioning (/api/v1/users) for most cases. It’s explicit, cacheable, and widely understood. Only use header versioning if you have specific requirements.

---

REST API Design Best Practices

1. Use Proper HTTP Methods

❌ Bad:

POST /users/123/delete
GET /users/create?name=John
POST /users/123/update

✅ Good:

DELETE /users/123
POST /users (with body)
PUT /users/123 (with body)

2. Use Nouns, Not Verbs

❌ Bad:

/getUsers
/createUser
/updateUser
/deleteUser

✅ Good:

GET /users
POST /users
PUT /users/123
DELETE /users/123

3. Use Plural Nouns for Collections

❌ Bad:

/user
/order

✅ Good:

/users
/orders

4. Use Hierarchical URLs

❌ Bad:

/orders?userId=123

✅ Good:

/users/123/orders

5. Use Consistent Naming

❌ Bad:

/users
/customers
/clients

✅ Good:

/users (consistent across API)

6. Return Proper Status Codes

❌ Bad:

// Always returns 200, even for errors
{
  "success": false,
  "error": "User not found"
}

✅ Good:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "User not found",
  "code": "USER_NOT_FOUND"
}

7. Use Pagination for Large Collections

❌ Bad:

GET /users  // Returns 10,000 users

✅ Good:

GET /users?page=1&limit=20
GET /users?offset=0&limit=20
GET /users?cursor=abc123&limit=20

Response:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1000,
    "hasNext": true
  }
}

8. Use Filtering, Sorting, Searching

GET /users?status=active&role=admin&sort=name&order=asc
GET /users?search=john&limit=10

9. Use HATEOAS (Hypermedia as the Engine of Application State)

Include links to related resources:

{
  "id": 123,
  "name": "John Doe",
  "links": {
    "self": "/users/123",
    "orders": "/users/123/orders",
    "profile": "/users/123/profile"
  }
}

---

LLD Connection: Implementing REST APIs

At the code level, REST APIs translate to controllers, services, and DTOs.

Controller Layer (HTTP Handling)

Python

user_controller.py

from flask import Flask, request, jsonify
from typing import Optional

app = Flask(__name__)

class UserController:
    def __init__(self, user_service):
        self.user_service = user_service

    def get_user(self, user_id: int):
        """GET /users/:id"""
        user = self.user_service.get_user(user_id)

        if not user:
            return jsonify({"error": "User not found"}), 404

        return jsonify(user), 200

    def create_user(self):
        """POST /users"""
        data = request.get_json()

        # Validate input
        if not data or 'email' not in data:
            return jsonify({"error": "Email required"}), 400

        user = self.user_service.create_user(data)
        return jsonify(user), 201, {'Location': f'/users/{user["id"]}'}

    def update_user(self, user_id: int):
        """PUT /users/:id"""
        data = request.get_json()

        if not data:
            return jsonify({"error": "Request body required"}), 400

        user = self.user_service.update_user(user_id, data)

        if not user:
            return jsonify({"error": "User not found"}), 404

        return jsonify(user), 200

    def delete_user(self, user_id: int):
        """DELETE /users/:id"""
        success = self.user_service.delete_user(user_id)

        if not success:
            return jsonify({"error": "User not found"}), 404

        return '', 204

# Routes
@app.route('/users/<int:user_id>', methods=['GET', 'PUT', 'DELETE'])
def user_detail(user_id):
    controller = UserController(user_service)

    if request.method == 'GET':
        return controller.get_user(user_id)
    elif request.method == 'PUT':
        return controller.update_user(user_id)
    elif request.method == 'DELETE':
        return controller.delete_user(user_id)

@app.route('/users', methods=['POST'])
def user_create():
    controller = UserController(user_service)
    return controller.create_user()

Java

UserController.java

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/users")
public class UserController {
    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping("/{id}")
    public ResponseEntity<UserDTO> getUser(@PathVariable int id) {
        // GET /users/:id
        Optional<UserDTO> user = userService.getUser(id);

        if (user.isEmpty()) {
            return ResponseEntity.notFound().build();
        }

        return ResponseEntity.ok(user.get());
    }

    @PostMapping
    public ResponseEntity<UserDTO> createUser(@RequestBody CreateUserRequest request) {
        // POST /users
        UserDTO user = userService.createUser(request);

        return ResponseEntity
            .status(HttpStatus.CREATED)
            .header("Location", "/users/" + user.getId())
            .body(user);
    }

    @PutMapping("/{id}")
    public ResponseEntity<UserDTO> updateUser(
            @PathVariable int id,
            @RequestBody UpdateUserRequest request) {
        // PUT /users/:id
        Optional<UserDTO> user = userService.updateUser(id, request);

        if (user.isEmpty()) {
            return ResponseEntity.notFound().build();
        }

        return ResponseEntity.ok(user.get());
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable int id) {
        // DELETE /users/:id
        boolean deleted = userService.deleteUser(id);

        if (!deleted) {
            return ResponseEntity.notFound().build();
        }

        return ResponseEntity.noContent().build();
    }
}

Service Layer (Business Logic)

Python

user_service.py

from typing import Optional, Dict, Any

class UserService:
    def __init__(self, user_repository):
        self.user_repository = user_repository

    def get_user(self, user_id: int) -> Optional[Dict[str, Any]]:
        """Business logic for getting user"""
        user = self.user_repository.find_by_id(user_id)

        if not user:
            return None

        # Transform to DTO
        return {
            "id": user.id,
            "name": user.name,
            "email": user.email,
            "status": user.status
        }

    def create_user(self, data: Dict[str, Any]) -> Dict[str, Any]:
        """Business logic for creating user"""
        # Validate business rules
        if self.user_repository.find_by_email(data['email']):
            raise ValueError("Email already exists")

        # Create user
        user = self.user_repository.create(data)

        return {
            "id": user.id,
            "name": user.name,
            "email": user.email,
            "status": user.status
        }

    def update_user(self, user_id: int, data: Dict[str, Any]) -> Optional[Dict[str, Any]]:
        """Business logic for updating user"""
        user = self.user_repository.find_by_id(user_id)

        if not user:
            return None

        # Update user
        updated_user = self.user_repository.update(user_id, data)

        return {
            "id": updated_user.id,
            "name": updated_user.name,
            "email": updated_user.email,
            "status": updated_user.status
        }

    def delete_user(self, user_id: int) -> bool:
        """Business logic for deleting user"""
        user = self.user_repository.find_by_id(user_id)

        if not user:
            return False

        self.user_repository.delete(user_id)
        return True

Java

UserService.java

import java.util.Optional;

@Service
public class UserService {
    private final UserRepository userRepository;

    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public Optional<UserDTO> getUser(int id) {
        // Business logic for getting user
        return userRepository.findById(id)
            .map(this::toDTO);
    }

    public UserDTO createUser(CreateUserRequest request) {
        // Validate business rules
        if (userRepository.findByEmail(request.getEmail()).isPresent()) {
            throw new ConflictException("Email already exists");
        }

        // Create user
        User user = userRepository.save(toEntity(request));
        return toDTO(user);
    }

    public Optional<UserDTO> updateUser(int id, UpdateUserRequest request) {
        // Business logic for updating user
        return userRepository.findById(id)
            .map(user -> {
                user.update(request);
                return toDTO(userRepository.save(user));
            });
    }

    public boolean deleteUser(int id) {
        // Business logic for deleting user
        if (!userRepository.existsById(id)) {
            return false;
        }

        userRepository.deleteById(id);
        return true;
    }

    private UserDTO toDTO(User user) {
        return new UserDTO(
            user.getId(),
            user.getName(),
            user.getEmail(),
            user.getStatus()
        );
    }
}

Error Handling

Python

error_handler.py

from flask import jsonify
from werkzeug.exceptions import HTTPException

class APIError(Exception):
    def __init__(self, message, status_code=400):
        self.message = message
        self.status_code = status_code

@app.errorhandler(APIError)
def handle_api_error(error):
    return jsonify({
        "error": error.message,
        "status": error.status_code
    }), error.status_code

@app.errorhandler(404)
def handle_not_found(error):
    return jsonify({
        "error": "Resource not found",
        "status": 404
    }), 404

@app.errorhandler(500)
def handle_server_error(error):
    return jsonify({
        "error": "Internal server error",
        "status": 500
    }), 500

Java

ErrorHandler.java

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class ErrorHandler {

    @ExceptionHandler(NotFoundException.class)
    public ResponseEntity<ErrorResponse> handleNotFound(NotFoundException e) {
        return ResponseEntity
            .status(404)
            .body(new ErrorResponse("Resource not found", 404));
    }

    @ExceptionHandler(BadRequestException.class)
    public ResponseEntity<ErrorResponse> handleBadRequest(BadRequestException e) {
        return ResponseEntity
            .status(400)
            .body(new ErrorResponse(e.getMessage(), 400));
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGeneric(Exception e) {
        return ResponseEntity
            .status(500)
            .body(new ErrorResponse("Internal server error", 500));
    }
}

---

Advanced Topics

Idempotency Keys

Make POST requests idempotent using idempotency keys:

POST /orders
Idempotency-Key: abc123-xyz789
Content-Type: application/json

{
  "productId": 456,
  "quantity": 2
}

Server behavior:

• First request: Create order, store idempotency key
• Duplicate request: Return same order (don’t create new one)

Content Negotiation

Support multiple formats:

GET /users/123
Accept: application/json

GET /users/123
Accept: application/xml

Field Selection

Let clients choose fields:

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

---

Key Takeaways

🎯 Resources are Nouns

Use nouns for resources, HTTP methods for actions. /users with GET, not /getUsers.

📊 Proper Status Codes

Use appropriate status codes. 201 for creation, 404 for not found, 400 for bad requests.

🔄 Idempotency Matters

GET, PUT, DELETE are idempotent. Design POST/PATCH to be idempotent when possible.

🏗️ Layered Architecture

Controllers handle HTTP, Services handle business logic, Repositories handle data access.

---

Next Steps

• Learn GraphQL Fundamentals - a query language for your API
• Understand gRPC & Protocol Buffers - high-performance RPC framework
• Master API Gateway Pattern - single entry point for your APIs