backend-api-development

🔧 Backend API Development Skill

Philosophy: APIs are contracts. Build them right the first time.

When to Use

Use this skill when:

• Creating a new API endpoint
• Building a new service/module
• Refactoring existing API code
• Adding new functionality to backend
• Need to follow RESTful/GraphQL best practices

Do NOT use this skill when:

• Just fixing a small bug (use debugging skill)
• Only modifying frontend (use frontend skill)
• Database-only changes (use database skill)

---

Prerequisites

Before starting:

• Requirements are clear (what the API should do)
• Understand the existing architecture
• Know the target stack (NestJS, Express, FastAPI, etc.)
• Database schema exists (or will be created)

---

Process

Phase 1: DESIGN 📐

Goal: Design the API before writing code.

Steps:

1. Define the Resource

   resource:
     name: User
     description: Represents a platform user
     domain: authentication
   

2. Design Endpoints (REST)

   endpoints:
     - method: GET
       path: /users
       description: List all users
       query_params: [page, limit, search]
       response: User[]
     
     - method: GET
       path: /users/:id
       description: Get single user
       response: User
     
     - method: POST
       path: /users
       description: Create new user
       body: CreateUserDto
       response: User
     
     - method: PUT
       path: /users/:id
       description: Update user
       body: UpdateUserDto
       response: User
     
     - method: DELETE
       path: /users/:id
       description: Delete user
       response: void
   

3. Define DTOs (Data Transfer Objects)

   // CreateUserDto
   interface CreateUserDto {
     email: string;      // required, email format
     password: string;   // required, min 8 chars
     name: string;       // required, min 2 chars
     role?: UserRole;    // optional, default: 'user'
   }
   
   // UpdateUserDto
   type UpdateUserDto = Partial<CreateUserDto>;
   
   // UserResponseDto
   interface UserResponseDto {
     id: string;
     email: string;
     name: string;
     role: UserRole;
     createdAt: DateTime;
     updatedAt: DateTime;
     // Note: password NOT included
   }