api-patterns

API Patterns Skill

TEMPLATE: This skill uses {{PLACEHOLDER}} tokens. Replace with your project values before use.

Purpose

Route to existing API patterns and provide checklists for safe, validated Express API route implementation.

When This Skill Applies

• Creating new Express API routes
• Implementing CRUD endpoints
• Adding request/response validation
• Handling webhooks (Linear, Confluence)
• Implementing error handling patterns

Authoritative References (MUST READ)

Pattern	Location	Purpose
User Context API	patterns_library/api/user-context-api.md	User-scoped operations
Admin Context API	patterns_library/api/admin-context-api.md	Admin-scoped operations
Zod Validation	patterns_library/api/zod-validation-api.md	Request/response validation
Webhook Handler	patterns_library/api/webhook-handler.md	Webhook processing

Stop-the-Line Conditions

FORBIDDEN Patterns

// FORBIDDEN: SQL injection via string interpolation
const result = await query(`SELECT * FROM users WHERE id = '${userId}'`);

// FORBIDDEN: Missing authentication check
router.get('/api/data', async (req, res) => {
  return res.json(await getAllData()); // No auth check!
});

// FORBIDDEN: Unvalidated user input
const { userId } = req.body;
// Must validate with Zod schema

// FORBIDDEN: Generic error responses
res.status(500).send("Error");
// Must use structured error response

CORRECT Patterns

// CORRECT: Parameterized queries
const result = await query('SELECT * FROM sessions WHERE org_id = $1', [orgId]);

// CORRECT: Auth check + validation
router.post('/api/resource', async (req: Request, res: Response) => {
  // 1. Validate input
  const parsed = RequestSchema.safeParse(req.body);
  if (!parsed.success) {
    return res.status(400).json({
      error: 'Validation failed',
      details: parsed.error.flatten(),
    });
  }

  // 2. Execute with parameterized query
  const result = await query(
    'INSERT INTO resources (name, org_id) VALUES ($1, $2) RETURNING *',
    [parsed.data.name, req.params.orgId]
  );

  // 3. Structured response
  res.status(201).json({ data: result.rows[0], success: true });
});