API design principles:
Resources are nouns
GET /users # List users
POST /users # Create user
GET /users/{id} # Get user
PUT /users/{id} # Update user
DELETE /users/{id} # Delete user
Actions use verbs in URLs
POST /users/{id}/activate
POST /users/{id}/reset-password
Consistent response format
{
"data": { ... },
"meta": { ... },
"errors": [ ... ]
}
Status codes
- 200: Success (GET, PUT, PATCH)
- 201: Created (POST)
- 204: No content (DELETE)
- 400: Bad request
- 401: Unauthorized
- 403: Forbidden
- 404: Not found
- 500: Server error
Documentation: OpenAPI/Swagger isn't optional—it's expected.