Building RESTful APIs: Best Practices

REST (Representational State Transfer) is the most popular architectural style for building web APIs. In this post, I'll share best practices I've learned from building production APIs.

Core Principles

1. Use HTTP Methods Correctly

• GET: Retrieve resources (safe and idempotent)
• POST: Create new resources
• PUT: Update/replace entire resources
• PATCH: Partial updates
• DELETE: Remove resources

2. Resource Naming

Use nouns, not verbs, and prefer plural names:

✅ Good:

• GET /api/users
• POST /api/users
• GET /api/users/123

❌ Bad:

• GET /api/getUsers
• POST /api/createUser

API Design Patterns

Versioning

Always version your API to maintain backward compatibility:

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

Pagination

For large datasets, implement pagination:

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

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Filtering and Sorting

GET /api/users?role=admin&sort=createdAt&order=desc

Error Handling

Return meaningful error responses:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  }
}

Status Codes

Use appropriate HTTP status codes:

• 200 OK: Successful GET, PUT, PATCH
• 201 Created: Successful POST
• 204 No Content: Successful DELETE
• 400 Bad Request: Client error
• 401 Unauthorized: Authentication required
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource doesn't exist
• 500 Internal Server Error: Server error

Security Best Practices

1. Always use HTTPS in production
2. Implement authentication (JWT, OAuth2)
3. Validate all inputs to prevent injection attacks
4. Rate limiting to prevent abuse
5. CORS configuration for web clients

Documentation

Good API documentation is crucial. Use tools like:

• Swagger/OpenAPI
• Postman Collections
• API Blueprint

Example: Task API

Here's a complete example:

@RestController
@RequestMapping("/api/v1/tasks")
public class TaskController {
    
    @GetMapping
    public ResponseEntity<Page<TaskDTO>> getAllTasks(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "20") int size
    ) {
        Pageable pageable = PageRequest.of(page, size);
        Page<TaskDTO> tasks = taskService.getAllTasks(pageable);
        return ResponseEntity.ok(tasks);
    }
    
    @PostMapping
    public ResponseEntity<TaskDTO> createTask(
        @Valid @RequestBody CreateTaskRequest request
    ) {
        TaskDTO task = taskService.createTask(request);
        return ResponseEntity
            .status(HttpStatus.CREATED)
            .body(task);
    }
    
    @GetMapping("/{id}")
    public ResponseEntity<TaskDTO> getTask(@PathVariable Long id) {
        return taskService.getTaskById(id)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
    }
}

Conclusion

Building great APIs requires attention to detail and following established conventions. These practices will help you create APIs that are easy to use, maintain, and scale.

Happy API building! 🎯