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 API route implementation. All API routes MUST use RLS context helpers -- see rls-patterns skill.

When This Skill Applies

• Creating new API routes
• Implementing CRUD endpoints
• Adding request/response validation
• Handling webhooks
• 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
Bonus Content	patterns_library/api/bonus-content-delivery.md	Protected content delivery

Stop-the-Line Conditions

FORBIDDEN Patterns

// FORBIDDEN: Direct ORM/DB calls (bypass RLS)
const users = await db.user.findMany();
// Must use: withUserContext, withAdminContext, or withSystemContext

// FORBIDDEN: Missing authentication check
export async function GET(req: Request) {
  return getUserData(); // No auth check!
}

// FORBIDDEN: Unvalidated user input
const { userId } = await req.json();
// Must validate with schema validation (Zod, Pydantic, etc.)

// FORBIDDEN: Generic error responses
return new Response("Error", { status: 500 });
// Must use structured error response

CORRECT Patterns

// CORRECT: RLS context + auth check
export async function GET(req: Request) {
  const { userId } = await auth();
  if (!userId) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const data = await withUserContext(db, userId, async (client) => {
    return client.user.findUnique({ where: { user_id: userId } });
  });

  return NextResponse.json(data);
}

// CORRECT: Schema validation
const schema = z.object({
  email: z.string().email(),
  name: z.string().min(1),
});

const result = schema.safeParse(body);
if (!result.success) {
  return NextResponse.json(
    { error: "Validation failed", details: result.error.flatten() },
    { status: 400 },
  );
}