Yasin Avci

Yasin Avci

Full-Stack Developer

Paris, France

Contact me
Back to articles
APIBackendArchitecture

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.

January 10, 20243 min read

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

  1. Client POSTs credentials to /auth/login
  2. API returns a JWT
  3. Client sends JWT in Authorization: Bearer xxx header

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

  1. Start simple — don't add features "just in case"
  2. Validate inputs aggressively — an overly permissive API is a nightmare to maintain
  3. Log everything — you'll need it to debug in production
  4. 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.