Designing a REST API That Ages Well
Versioning, error handling, pagination... The conventions that make the difference between a maintainable API and a technical nightmare.
A poorly designed API is technical debt that accumulates with each new client. Here are the principles I apply to create APIs that remain maintainable after years of evolution.
Naming Endpoints: Clarity First
Resources, Not Actions
❌ GET /getUsers
❌ POST /createUser
❌ PUT /updateUser/123
âś… GET /users
âś… POST /users
âś… PUT /users/123
The URL describes the resource, the HTTP verb describes the action.
Plural and Consistency
Choose a convention and stick to it:
âś… /users, /products, /orders
❌ /user, /products, /order (inconsistent)
Nested Relations in Moderation
âś… GET /users/123/orders (a user's orders)
❌ GET /users/123/orders/456/items/789/details (too deep)
Beyond 2 levels, prefer separate endpoints with filters.
Error Handling: Being Explicit
Appropriate HTTP Codes
| Code | Usage | |------|-------| | 200 | Success | | 201 | Resource created | | 400 | Validation error | | 401 | Not authenticated | | 403 | Not authorized | | 404 | Resource not found | | 500 | Server error |
Standardized Error Format
{
"error": {
"code": "VALIDATION_ERROR",
"message": "The provided data is invalid",
"details": [
{
"field": "email",
"message": "Invalid email format"
}
]
}
}
Always the same format, always the same level of detail. The client knows what to expect.
Pagination: Never Return Everything
The Classic Offset/Limit Pattern
GET /users?offset=0&limit=20
Simple, but problematic on large tables (degraded performance over time).
Cursor-Based for Large Volumes
GET /users?cursor=abc123&limit=20
The cursor encodes the position in the list. More performant, but more complex to implement.
The Paginated Response
{
"data": [...],
"pagination": {
"total": 1234,
"limit": 20,
"offset": 0,
"hasMore": true
}
}
Versioning: Anticipating Change
In the URL (Recommended)
GET /v1/users
GET /v2/users
Clear, explicit, easy to route.
In Headers
GET /users
Accept: application/vnd.api+json; version=2
More "RESTful" in theory, but less practical day-to-day.
Golden Rule
- Adding fields is backward compatible
- Removing/modifying fields requires a new version
- Maintain maximum 2 versions in parallel
Authentication: JWT with Caution
The Classic Flow
- Client POSTs credentials to
/auth/login - API returns a JWT
- Client sends JWT in
Authorization: Bearer xxxheader
Pitfalls to Avoid
❌ Storing sensitive data in JWT (visible client-side)
❌ Tokens that never expire
❌ No revocation mechanism
âś… Minimal payload (user_id, roles)
âś… Short expiration (15min - 1h) + refresh token
âś… Blacklist of revoked tokens
Documentation: The Investment That Pays
OpenAPI (Swagger) Minimum
paths:
/users:
get:
summary: List of users
parameters:
- name: limit
in: query
schema:
type: integer
default: 20
responses:
'200':
description: Paginated list of users
Auto-generated documentation is always up to date.
Concrete Examples
For each endpoint, provide:
- A request example
- A success response example
- An error response example
What I Wish I Had Known Earlier
- Start simple — don't add features "just in case"
- Validate inputs aggressively — an overly permissive API is a nightmare to maintain
- Log everything — you'll need it to debug in production
- Test with real clients — unit tests aren't enough
A good API is invisible. The client uses it without asking questions, and you maintain it without fear of breaking everything.
