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.