Backend Patterns Skill

Modern backend patterns and best practices for building scalable APIs.

API Design Patterns

RESTful Conventions

GET /api/v1/users # List users GET /api/v1/users/:id # Get user POST /api/v1/users # Create user PUT /api/v1/users/:id # Replace user PATCH /api/v1/users/:id # Update user DELETE /api/v1/users/:id # Delete user

Nested resources

GET /api/v1/users/:id/posts POST /api/v1/users/:id/posts

Actions as resources

POST /api/v1/auth/login POST /api/v1/auth/logout POST /api/v1/passwords/reset

Response Format

// Success response interface SuccessResponse<T> { success: true; data: T; meta?: { page: number; perPage: number; total: number; totalPages: number; }; }

// Error response interface ErrorResponse { success: false; error: { code: string; message: string; details?: Array<{ field: string; message: string; }>; }; }

Status Codes

Code Meaning Usage

200 OK Successful GET, PUT, PATCH

201 Created Successful POST

204 No Content Successful DELETE

400 Bad Request Validation error

401 Unauthorized Missing/invalid auth

403 Forbidden No permission

404 Not Found Resource doesn't exist

409 Conflict Duplicate resource

422 Unprocessable Business logic error

500 Server Error Unexpected error

Authentication Patterns

JWT Flow

// Login - generate tokens async function login(email: string, password: string) { const user = await db.users.findByEmail(email); if (!user || !await verifyPassword(password, user.password)) { throw new HTTPException(401, { message: 'Invalid credentials' }); }

const accessToken = await generateAccessToken(user); const refreshToken = await generateRefreshToken(user);

// Store refresh token await db.refreshTokens.create({ userId: user.id, token: refreshToken, expiresAt: addDays(new Date(), 7), });

return { accessToken, refreshToken, user }; }

// Token generation async function generateAccessToken(user: User) { return jwt.sign( { sub: user.id, email: user.email, role: user.role }, process.env.JWT_SECRET, { expiresIn: '15m' } ); }

// Token refresh async function refreshAccessToken(refreshToken: string) { const stored = await db.refreshTokens.findByToken(refreshToken); if (!stored || stored.expiresAt < new Date()) { throw new HTTPException(401, { message: 'Invalid refresh token' }); }

const user = await db.users.findById(stored.userId); return generateAccessToken(user); }

Auth Middleware

export async function authMiddleware(c: Context, next: Next) { const authHeader = c.req.header('Authorization');

if (!authHeader?.startsWith('Bearer ')) { throw new HTTPException(401, { message: 'Missing token' }); }

const token = authHeader.slice(7);

try { const payload = await jwt.verify(token, process.env.JWT_SECRET); c.set('userId', payload.sub); c.set('userRole', payload.role); await next(); } catch { throw new HTTPException(401, { message: 'Invalid token' }); } }

// Role-based authorization export function requireRole(...roles: string[]) { return async (c: Context, next: Next) => { const userRole = c.get('userRole'); if (!roles.includes(userRole)) { throw new HTTPException(403, { message: 'Forbidden' }); } await next(); }; }

Validation Patterns

Zod Schemas

import { z } from 'zod';

// User schemas export const createUserSchema = z.object({ email: z.string().email('Invalid email'), name: z.string().min(2).max(100), password: z.string() .min(8, 'Password must be at least 8 characters') .regex(/[A-Z]/, 'Must contain uppercase') .regex(/[0-9]/, 'Must contain number'), });

export const updateUserSchema = createUserSchema.partial();

// Query params export const paginationSchema = z.object({ page: z.coerce.number().min(1).default(1), perPage: z.coerce.number().min(1).max(100).default(20), sort: z.enum(['createdAt', 'name']).default('createdAt'), order: z.enum(['asc', 'desc']).default('desc'), });

// Using with Hono app.post('/users', zValidator('json', createUserSchema), async (c) => { const data = c.req.valid('json'); // data is fully typed });

Error Handling

Central Error Handler

export function errorHandler(err: Error, c: Context) { console.error('Error:', err);

// HTTP exceptions if (err instanceof HTTPException) { return c.json({ success: false, error: { code: 'HTTP_ERROR', message: err.message }, }, err.status); }

// Validation errors if (err instanceof ZodError) { return c.json({ success: false, error: { code: 'VALIDATION_ERROR', message: 'Invalid input', details: err.errors.map(e => ({ field: e.path.join('.'), message: e.message, })), }, }, 400); }

// Database errors if (err.code === '23505') { // Unique violation return c.json({ success: false, error: { code: 'CONFLICT', message: 'Resource already exists' }, }, 409); }

// Unknown errors return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' }, }, 500); }

Caching Patterns

Redis Caching

import { Redis } from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

// Cache-aside pattern async function getUserById(id: string): Promise<User> { const cacheKey = user:${id};

// Try cache first const cached = await redis.get(cacheKey); if (cached) { return JSON.parse(cached); }

// Fetch from database const user = await db.users.findById(id); if (!user) throw new HTTPException(404);

// Cache for 5 minutes await redis.setex(cacheKey, 300, JSON.stringify(user));

return user; }

// Invalidate on update async function updateUser(id: string, data: UpdateUserInput) { const user = await db.users.update(id, data); await redis.del(user:${id}); return user; }

Rate Limiting

import { rateLimiter } from 'hono-rate-limiter';

// Apply rate limiting app.use( '/api/*', rateLimiter({ windowMs: 60 * 1000, // 1 minute limit: 100, // 100 requests per minute keyGenerator: (c) => c.get('userId') || c.req.header('x-forwarded-for'), }) );

// Stricter limits for auth endpoints app.use( '/api/auth/*', rateLimiter({ windowMs: 15 * 60 * 1000, // 15 minutes limit: 5, // 5 attempts }) );

Database Patterns

Repository Pattern

class UserRepository { async findById(id: string): Promise<User | null> { return db.query.users.findFirst({ where: eq(users.id, id), }); }

async findByEmail(email: string): Promise<User | null> { return db.query.users.findFirst({ where: eq(users.email, email), }); }

async create(data: CreateUserInput): Promise<User> { const [user] = await db.insert(users).values(data).returning(); return user; }

async update(id: string, data: UpdateUserInput): Promise<User> { const [user] = await db .update(users) .set({ ...data, updatedAt: new Date() }) .where(eq(users.id, id)) .returning(); return user; }

async delete(id: string): Promise<void> { await db.delete(users).where(eq(users.id, id)); } }

Transaction Pattern

async function createOrder(userId: string, items: OrderItem[]) { return db.transaction(async (tx) => { // Create order const [order] = await tx .insert(orders) .values({ userId, status: 'pending' }) .returning();

// Create order items
await tx.insert(orderItems).values(
  items.map(item => ({
    orderId: order.id,
    productId: item.productId,
    quantity: item.quantity,
  }))
);

// Update inventory
for (const item of items) {
  await tx
    .update(products)
    .set({ stock: sql`stock - ${item.quantity}` })
    .where(eq(products.id, item.productId));
}

return order;

}); }