REST API Design — Best Practices for Interviews
The Interview Question
What are the key principles of REST API design? How do you design a good API?
Expert Answer
REST APIs are built around resources (nouns, not verbs) accessed through standard HTTP methods. The core principles: use plural nouns for resource URLs (/users, not /getUsers or /user). Map CRUD operations to HTTP methods — GET for read, POST for create, PUT for full update, PATCH for partial update, DELETE for remove. Return appropriate status codes — 200 for success, 201 for created, 204 for no content (successful delete), 400 for client error, 401 for unauthorized, 403 for forbidden, 404 for not found, 409 for conflict, 422 for validation failure, 500 for server error. Design for collections: support filtering (?status=active), sorting (?sort=-created_at), pagination (?page=2&limit=20 or cursor-based), and field selection (?fields=id,name). Version your API from day one (/api/v1/users or via Accept header). Return consistent error response bodies with a code, message, and details field. Nest related resources logically: /users/123/orders is the orders for user 123.
Key Points to Hit in Your Answer
- Resources are nouns (/users), not verbs (/getUsers)
- HTTP methods map to CRUD: GET=read, POST=create, PUT=replace, PATCH=update, DELETE=remove
- Status codes matter: 2xx success, 4xx client error, 5xx server error
- Pagination: offset-based (simple, bad at scale) vs cursor-based (consistent, scalable)
- Version from day one: /api/v1/ or Accept: application/vnd.api+json;version=1
- Idempotency: GET, PUT, DELETE should be idempotent; POST is not
- HATEOAS: include links to related resources (often skipped in practice)
Code Example
// Good REST design
GET /api/v1/users // list users
GET /api/v1/users/123 // get specific user
POST /api/v1/users // create user
PATCH /api/v1/users/123 // update user fields
DELETE /api/v1/users/123 // delete user
GET /api/v1/users/123/orders // user's orders
// Filtering, sorting, pagination
GET /api/v1/users?status=active&sort=-created_at&page=2&limit=20
// Consistent error response
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request body",
"details": [
{ "field": "email", "message": "Must be a valid email" }
]
}
}
// Cursor-based pagination (better for large datasets)
GET /api/v1/users?limit=20&after=eyJpZCI6MTIzfQ==
// Response includes:
{
"data": [...],
"pagination": {
"next_cursor": "eyJpZCI6MTQzfQ==",
"has_more": true
}
}What Interviewers Are Really Looking For
Know the HTTP method semantics cold — especially the difference between PUT (replace entire resource) and PATCH (partial update). Pagination is a common follow-up: explain why cursor-based is better than offset at scale (offset skips become expensive). Idempotency is critical for production APIs — explain what it means and why POST isn't idempotent. Mention rate limiting and authentication as cross-cutting concerns.
Practice This Question with AI Grading
Reading about interview questions is a start — but practicing with real-time AI feedback is how you actually get better. Goliath Prep grades your answers instantly and tells you exactly what you're missing.
Start Practicing Free →