Backend

Versioning: prefix routes with /v1/, /v2/ etc. Never break a published API version.

Error Response Format

Return consistent, machine-readable errors:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Must be a valid email address" }
    ],
    "traceId": "abc123"
  }
}

Always include a traceId for debuggability in production.

Pagination

Use cursor-based pagination for large or real-time datasets; offset for simple cases:

Cursor-based (preferred):

{
  "data": [...],
  "pagination": {
    "hasNextPage": true,
    "endCursor": "eyJpZCI6MTAwfQ=="
  }
}

Offset-based:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "perPage": 20,
    "total": 543
  }
}

Authentication Patterns

• JWT (stateless): use short-lived access tokens (15 min) + refresh tokens (7 days stored in HttpOnly cookie)
• Session-based: server stores session; send HttpOnly; Secure; SameSite=Strict cookie
• API keys: for machine-to-machine; hash the key in the DB (never store plaintext)
• OAuth 2.0 / OIDC: for third-party login; delegate to an identity provider

Validate tokens on every request. Never trust client-supplied user IDs without re-verifying the token.

Database Best Practices

Schema design:

• Use UUIDs (v4 or v7) for primary keys in distributed systems
• Add created_at and updated_at timestamps to every table
• Use soft deletes (deleted_at) for data that needs audit trails
• Index foreign keys and any column used in frequent WHERE/ORDER BY clauses

Query discipline:

• Use an ORM or query builder — avoid raw string SQL except for complex reports
• Always paginate queries that can return unbounded rows
• Avoid N+1: use eager loading (.include(), JOIN, dataloader)
• Wrap related mutations in a transaction

Migrations:

• Use a migration tool (Flyway, Liquibase, Prisma Migrate, Alembic)
• Migrations must be backward-compatible with the previous deployment (expand-contract pattern)
• Never edit a committed migration — create a new one

Service Layer Pattern

Organise code in layers:

Controller (HTTP) → Service (business logic) → Repository (data access)

• Controllers validate input and map HTTP ↔ domain
• Services contain all business rules; no HTTP/DB concerns
• Repositories encapsulate all DB queries; return domain objects

Background Jobs

• Use a queue (BullMQ, Celery, Sidekiq) for work that shouldn't block an HTTP response
• Jobs must be idempotent — safe to retry
• Implement exponential backoff with jitter for retries
• Dead-letter queue for failed jobs after max retries

Examples

// Controller: validate input, delegate to service
app.post('/users', async (req, res) => {
  const parsed = createUserSchema.safeParse(req.body);
  if (!parsed.success) {
    return res.status(422).json({ error: parsed.error.format() });
  }
  const user = await userService.create(parsed.data);
  res.status(201).json(user);
});

// Service: business logic only
class UserService {
  async create(data: CreateUserDto) {
    const existing = await this.userRepo.findByEmail(data.email);
    if (existing) throw new ConflictError('Email already registered');
    return this.userRepo.create({ ...data, passwordHash: await hash(data.password) });
  }
}

References

• REST API Design Best Practices
• HTTP Status Codes
• Cursor-based Pagination
• The Twelve-Factor App
• Prisma ORM