API Design Principles in 2026 — REST Maturity, Ergonomics, and What the Best APIs Get Right

POST /api
Body: { "action": "get_user", "userId": "123" }

GET /api/users/123
POST /api/users
POST /api/users/123/delete

GET /api/users/123 → 200
POST /api/users → 201
PUT /api/users/123 → 200
DELETE /api/users/123 → 204

{
  "id": "123",
  "name": "Alice",
  "_links": {
    "self": { "href": "/users/123" },
    "orders": { "href": "/users/123/orders" },
    "edit": { "href": "/users/123", "method": "PUT" }
  }
}

✓ Good: /users/{id}/orders, /orders/{id}/items
✗ Bad: /user/{id}/order, /getOrders, /Orders

✓ Good: plural nouns (resources), lowercase
✗ Bad: mixed case, verbs, singular

✓ Collection: GET /users, /teams, /invoices
✓ Singular: GET /users/123, /teams/abc, /invoices/xyz

✓ Nested: /users/123/orders (user's orders)
✓ Filtered: GET /orders?user_id=123 (alternative)

✓ List: GET /invoices?status=draft
✗ Bad: GET /drafts, GET /invoices/draft

// HTTP method choice example
PUT /users/123
{
  "name": "Alice",
  "email": "alice@example.com",
  "role": "admin"  // Must include all fields
}

PATCH /users/123
{
  "role": "user"   // Only update this field
}

// Offset: skip N, take M
GET /users?offset=0&limit=10 → users 0-9
GET /users?offset=10&limit=10 → users 10-19

// Problem: If user #5 is inserted between requests:
// Request 1: returns users [0-9]
// Request 2: returns [10-19] (but user who was #10 is now #11!)
// Result: user #10 is skipped

// Cursor: position encoded as base64(id, timestamp)
GET /users?limit=10 → {
  data: [...],
  next_cursor: "eyJpZCI6IjEyMyIsInRzIjoxMjM0NTY3ODkwfQ=="
}

GET /users?limit=10&cursor=eyJpZCI6IjEyMyIsInRzIjoxMjM0NTY3ODkwfQ== → {
  data: [...],
  next_cursor: "..."
}

// Pros: Consistent regardless of insertions/deletions
// Cons: Cannot jump to page N (must iterate)

// Keyset: "give me next 10 after id=123"
GET /users?limit=10&after_id=123 → {
  data: [...],
  next_after_id: "456"
}

// Most efficient at scale
// Works with database indices

// Pagination implementation
export async function paginateUsers(
  limit: number = 10,
  cursor?: string
): Promise<{
  data: User[];
  next_cursor: string | null;
}> {
  const query = db.select('*').from('users').limit(limit + 1);

  if (cursor) {
    // Decode cursor to find starting position
    const { id } = JSON.parse(Buffer.from(cursor, 'base64').toString());
    query.where('id', '>', id);
  }

  const rows = await query.exec();
  const hasMore = rows.length > limit;
  const data = rows.slice(0, limit);

  const nextCursor = hasMore
    ? Buffer.from(JSON.stringify({ id: data[data.length - 1].id })).toString('base64')
    : null;

  return { data, next_cursor: nextCursor };
}

// RFC 7807 Problem Details
{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Failed",
  "status": 400,
  "detail": "The 'email' field must be a valid email address.",
  "instance": "/users/creation",
  "invalid_fields": {
    "email": "Must be valid email"
  },
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

// error-handler.ts
import express from 'express';

class ApiError extends Error {
  constructor(
    public type: string,
    public title: string,
    public status: number,
    public detail: string,
    public instance?: string,
    public extra?: Record<string, any>
  ) {
    super(detail);
  }
}

export function errorHandler(
  err: Error,
  req: express.Request,
  res: express.Response,
  next: express.NextFunction
) {
  if (err instanceof ApiError) {
    return res.status(err.status).json({
      type: err.type,
      title: err.title,
      status: err.status,
      detail: err.detail,
      instance: err.instance || req.path,
      trace_id: req.headers['x-trace-id'],
      ...err.extra,
    });
  }

  // Generic error
  res.status(500).json({
    type: 'https://api.example.com/errors/internal-error',
    title: 'Internal Server Error',
    status: 500,
    detail: 'An unexpected error occurred.',
    instance: req.path,
    trace_id: req.headers['x-trace-id'],
  });
}

app.use(errorHandler);

// Usage
app.post('/users', (req, res, next) => {
  if (!req.body.email) {
    return next(
      new ApiError(
        'https://api.example.com/errors/validation-error',
        'Validation Failed',
        400,
        "The 'email' field is required.",
        '/users',
        { invalid_fields: { email: 'Required' } }
      )
    );
  }
});

// Default: minimal response
GET /users/123 → {
  "id": "123",
  "name": "Alice",
  "email": "alice@example.com"
}

// Opt-in: include related resources
GET /users/123?include=orders,profile → {
  "id": "123",
  "name": "Alice",
  "email": "alice@example.com",
  "orders": [...],
  "profile": {...}
}

// Opt-in: sparse fields
GET /users/123?fields=id,name → {
  "id": "123",
  "name": "Alice"
}

// Defaults: same as /users?limit=20&offset=0&sort=-created_at
GET /users

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1645000000
Retry-After: 60

// Or newer standard (IETF draft)
RateLimit-Limit: 1000
RateLimit-Remaining: 999
RateLimit-Reset: 1645000000

// rate-limit-middleware.ts
import rateLimit from 'express-rate-limit';

const limiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 1000, // requests per window
  standardHeaders: true, // Return rate limit info in RateLimit-* headers
  legacyHeaders: false, // Disable X-RateLimit-* headers
  skip: (req) => req.user?.isPremium, // Skip for premium users
});

app.use(limiter);

// Custom headers
app.use((req, res, next) => {
  res.set({
    'RateLimit-Limit': '1000',
    'RateLimit-Remaining': String(1000 - req.rateLimit.current),
    'RateLimit-Reset': String(Math.ceil(Date.now() / 1000) + 60),
  });
  next();
});

HTTP/1.1 200 OK
Deprecation: true
Sunset: Mon, 15 Sep 2026 00:00:00 GMT
Link: <https://docs.example.com/v2/users>; rel="successor-version"
Warning: 299 - "This endpoint will be shut down on 2026-09-15. Use /v2/users instead."

// Deprecate endpoint
app.get('/v1/users/:id', deprecationMiddleware, (req, res) => {
  res.set({
    'Deprecation': 'true',
    'Sunset': new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toUTCString(),
    'Link': '<https://docs.example.com/v2/users>; rel="successor-version"',
  });
  
  // Return data from v2 handler
  return handleUserRequest(req, res);
});

function deprecationMiddleware(req, res, next) {
  res.set({
    'Deprecation': 'true',
    'Sunset': 'Mon, 15 Sep 2026 00:00:00 GMT',
  });
  next();
}