A well-designed REST API is intuitive, consistent, and a pleasure to use. Here are principles that lead to APIs developers love.
Resource Naming
Use Nouns, Not Verbs
❌ Bad
GET /getUsers
POST /createUser
PUT /updateUser/123
DELETE /deleteUser/123
✅ Good
GET /users
POST /users
PUT /users/123
DELETE /users/123
Use Plural Nouns
❌ Inconsistent
GET /user/123
GET /users
✅ Consistent
GET /users/123
GET /users
Nest Resources Logically
# User's posts
GET /users/123/posts
POST /users/123/posts
# Post's comments
GET /posts/456/comments
POST /posts/456/comments
# Avoid deep nesting (max 2 levels)
❌ /users/123/posts/456/comments/789/replies
✅ /comments/789/replies
HTTP Methods
Method | Usage | Idempotent | Safe
---------+--------------------------+------------+------
GET | Retrieve resource(s) | Yes | Yes
POST | Create resource | No | No
PUT | Replace resource | Yes | No
PATCH | Partial update | No* | No
DELETE | Remove resource | Yes | No
* PATCH can be idempotent depending on implementation
Examples
Loading code block...
HTTP Status Codes
Success Codes
200 OK - General success
201 Created - Resource created (POST)
204 No Content - Success, no body (DELETE)
Client Error Codes
400 Bad Request - Invalid input
401 Unauthorized - No/invalid authentication
403 Forbidden - Authenticated but not allowed
404 Not Found - Resource doesn't exist
409 Conflict - Resource conflict
422 Unprocessable - Validation failed
429 Too Many Reqs - Rate limited
Server Error Codes
500 Internal Error - Server error
502 Bad Gateway - Upstream error
503 Unavailable - Temporarily unavailable
504 Gateway Timeout - Upstream timeout
Error Responses
Consistent Structure
Loading code block...
Implementation
Loading code block...
Pagination
Offset Pagination
Loading code block...
Cursor Pagination (Preferred)
Loading code block...
Filtering, Sorting, and Fields
Loading code block...
Request/Response Design
Consistent Envelopes
Loading code block...
Use Camel Case
Loading code block...
ISO 8601 for Dates
Loading code block...
Headers
Request Headers
Loading code block...
Response Headers
Loading code block...
Versioning
URL Versioning (Recommended)
GET /v1/users
GET /v2/users
Header Versioning
Loading code block...
HATEOAS (Optional)
Loading code block...
Documentation
Loading code block...
Conclusion
Good REST API design is about consistency and predictability. Follow conventions, use proper HTTP methods and status codes, and document everything.
The best API is one where developers can guess the correct endpoint without reading documentation. Achieve that through consistent patterns applied throughout.