name: api-endpoint-builder description: "Build REST API endpoints when designing or implementing API routes with security best practices. Not for client-side fetching or non-API logic." context: fork agent: Plan allowed-tools: Read, Write, Edit, Bash

API Endpoint Builder

Build REST API endpoints following security and performance best practices.

Workflow

Execute this process for building API endpoints:

1. Plan the Endpoint

• Determine HTTP method (GET, POST, PUT, DELETE)
• Design path pattern following REST conventions
• Identify required input validation
• Define output format (JSON, status codes)

2. Validate Security

• Input validation and sanitization
• Authentication/authorization checks
• Rate limiting considerations
• SQL injection prevention
• XSS protection

3. Implement Structure

• Create route handler file
• Add middleware for validation
• Implement error handling
• Add request/response types
• Include logging

4. Add Tests

• Unit tests for handler
• Integration tests for route
• Validation test cases
• Error scenario tests

5. Verify Compliance

• Check error codes follow conventions
• Verify response format consistency
• Validate security headers
• Test input validation

Example Implementation

// POST /api/users
export async function POST(request: NextRequest) {
  try {
    // 1. Validate input
    const body = await request.json();
    const validated = CreateUserSchema.parse(body);

    // 2. Check authentication
    const user = await authenticate(request);
    if (!user || !hasPermission(user, "create_user")) {
      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
    }

    // 3. Create user
    const newUser = await createUser(validated);

    // 4. Return response
    return NextResponse.json({ user: sanitizeUser(newUser) }, { status: 201 });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { error: "Invalid input", details: error.errors },
        { status: 400 },
      );
    }

    logger.error("Create user failed", { error, userId: user?.id });
    return NextResponse.json(
      { error: "Internal server error" },
      { status: 500 },
    );
  }
}

Best Practices

• Always validate input - Use Zod or similar for schema validation
• Use parameterized queries - Prevent SQL injection
• Implement rate limiting - Protect against abuse
• Log security events - Track authentication failures
• Use proper status codes - 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 500 Internal Server Error
• Sanitize output - Prevent XSS attacks
• Version your APIs - Use /api/v1/ paths
• Document responses - Use OpenAPI/Swagger

Integration

This skill integrates with:

• security - Security patterns and validation
• backend-patterns - Backend best practices
• engineering-lifecycle - Testing requirements

Genetic Code

This component carries essential Seed System principles for context: fork isolation:

<critical_constraint> MANDATORY: All components MUST be self-contained (zero .claude/rules dependency) MANDATORY: Achieve 80-95% autonomy (0-5 AskUserQuestion rounds per session) MANDATORY: Description MUST use What-When-Not format in third person MANDATORY: No component references another component by name in description MANDATORY: Progressive disclosure - references/ for detailed content MANDATORY: Use XML for control (mission_control, critical_constraint), Markdown for data No exceptions. Portability invariant must be maintained. </critical_constraint>

Delta Standard: Good Component = Expert Knowledge − What Claude Already Knows

Recognition Questions:

• "Would Claude know this without being told?" → Delete (zero delta)
• "Can this work standalone?" → Fix if no (non-self-sufficient)
• "Did I read the actual file, or just see it in grep?" → Verify before claiming MANDATORY: Use parameterized queries to prevent SQL injection MANDATORY: Implement proper authentication/authorization checks MANDATORY: Return appropriate HTTP status codes (400, 401, 403, 500) MANDATORY: Log security events (authentication failures, errors) No exceptions. API security is non-negotiable. </critical_constraint>