devjarus/api-design

API Design

URL Structure

• Use nouns, never verbs: /users, not /getUsers
• Always plural: /orders, /products
• Nest resources max 2 levels deep: /users/{id}/orders is fine; avoid /users/{id}/orders/{id}/items/{id}
• Use kebab-case for multi-word segments: /blog-posts, /user-profiles

HTTP Methods

| Method | Semantics | |--------|-----------| | GET | Read resource(s), idempotent, no body | | POST | Create a new resource or trigger an action | | PUT | Replace a resource entirely | | PATCH | Partial update of a resource | | DELETE | Remove a resource, idempotent |

Response Format

Success:

{
  "data": { ... },
  "meta": { "requestId": "abc123", "timestamp": "2024-01-01T00:00:00Z" }
}

Error:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [{ "field": "email", "issue": "Invalid format" }]
  }
}

Status Codes

| Code | When to use | |------|-------------| | 200 | Successful GET, PUT, PATCH | | 201 | Successful POST that created a resource | | 204 | Successful DELETE or action with no response body | | 400 | Bad request — malformed syntax or invalid parameters | | 401 | Not authenticated | | 403 | Authenticated but not authorized | | 404 | Resource not found | | 409 | Conflict — duplicate, state mismatch | | 422 | Validation failed — well-formed but semantically invalid | | 500 | Unexpected server error |

Pagination

Cursor-based (for large or frequently updated datasets):

{
  "data": [...],
  "meta": {
    "nextCursor": "eyJpZCI6MTAwfQ==",
    "hasMore": true
  }
}

Offset-based (for simple, small datasets):

{
  "data": [...],
  "meta": {
    "total": 250,
    "page": 2,
    "perPage": 25,
    "totalPages": 10
  }
}

Always return a meta object even when there is only one page.

Versioning

• Major breaking changes: URL prefix — /v1/users, /v2/users
• Additive changes (new optional fields, new endpoints) are backward compatible and do not require a version bump
• Deprecate old versions with Sunset response headers before removing

Routes are transports, not logic

Every route handler should be roughly 10 lines: (1) parse input, (2) call a core function, (3) return the serialized result, (4) catch errors and map them to status codes. Business logic lives in the core library or service layer, not in the route.

// GOOD — thin wrapper around a core function
app.get('/api/posts/:slug', async (req, res, next) => {
  try {
    const post = await posts.findBySlug(req.params.slug);
    if (!post) return res.status(404).json({ error: { code: 'NOT_FOUND', message: 'Post not found' } });
    return res.status(200).json({ data: post });
  } catch (err) {
    return next(err);
  }
});

// BAD — business logic embedded in the route
app.get('/api/posts/:slug', async (req, res) => {
  const db = getDb();
  const row = await db.prepare('SELECT * FROM posts WHERE slug = ?').get(req.params.slug);
  if (!row) return res.status(404).json(...);
  const excerpt = row.content.split('\n').slice(0, 3).join(' ').substring(0, 150);  // ← logic
  const tags = row.tags?.split(',') ?? [];                                           // ← logic
  return res.status(200).json({ data: { ...row, excerpt, tags } });
});

Why it matters: testing the core library is effectively testing every route, because routes add nothing beyond transport glue. If your route handler is >15 lines or contains branching business logic beyond error-to-status mapping, extract it into a pure core function and call that from the route.

Applies to: Next.js Route Handlers, Express middlewares, FastAPI endpoints, Gin handlers, Rails controllers — any framework where you're tempted to put logic "right in the handler because it's convenient."

Exception: trivial projections (e.g., picking 3 fields out of a row for a list view) are fine inline. The rule targets branching, validation, data transformation, and external calls — not one-line field selection.