REST APIs

Building RESTful Services

REST (Representational State Transfer) is an architectural style for designing networked applications using standard HTTP methods.

REST Principles

• Stateless: Each request contains all needed information
• Resource-based: URLs represent resources, not actions
• HTTP Methods: Use verbs appropriately (GET, POST, PUT, DELETE)
• Representations: Resources can have multiple formats (JSON, XML)

URL Design

GET    /api/users          # List users
GET    /api/users/:id       # Get single user
POST   /api/users           # Create user
PUT    /api/users/:id       # Update user
DELETE /api/users/:id       # Delete user

# Nested resources
GET    /api/users/:id/posts # User's posts

Response Codes

• 200 OK: Successful GET/PUT
• 201 Created: Successful POST
• 204 No Content: Successful DELETE
• 400 Bad Request: Invalid input
• 401 Unauthorized: Authentication required
• 404 Not Found: Resource doesn't exist
• 422 Unprocessable: Validation errors

Best Practices

• Use plural nouns for resources
• Version your API (/api/v1/)
• Return consistent error shapes
• Implement pagination for lists
• Use HATEOAS for discoverability