workspace-v1/orchestration/checklists/CHECKLIST-CODE-REVIEW-API.md

CHECKLIST DE CODE REVIEW PARA APIs

Versión: 1.0 Fecha: 2025-11-23 Autor: Architecture-Analyst Motivación: Prevenir bugs de configuración de rutas API mediante revisión sistemática

---

PROBLEMA IDENTIFICADO

La falta de un checklist específico para revisión de código API resultó en:

1. Bugs de duplicación de rutas (/api/api/)
2. Configuraciones inconsistentes entre backend y frontend
3. URLs hardcodeadas en lugar de usar variables de entorno
4. Falta de validación de configuración de rutas
5. Errores que solo se detectaban en runtime

Este checklist establece revisiones obligatorias antes de aprobar cualquier PR que involucre APIs.

---

CHECKLIST COMPLETO

SECCIÓN 1: CONFIGURACIÓN DE BASE URL

1.1. Variables de Entorno

• Verificar que existe variable VITE_API_URL en .env (frontend)
• Verificar que existe variable PORT en .env (backend)
• Verificar que NO hay /api en la variable VITE_API_URL
• Verificar que variables están documentadas en .env.example
• Verificar configuración para todos los ambientes (dev, staging, prod)

Ejemplo Correcto:

# .env
VITE_API_URL=http://localhost:3000  # ✅ Sin /api al final

Ejemplo Incorrecto:

# .env
VITE_API_URL=http://localhost:3000/api  # ❌ Incluye /api

1.2. Configuración de API Client

• Verificar que baseURL incluye ${VITE_API_URL}/api
• Verificar que baseURL NO incluye rutas de recursos
• Verificar que timeout está configurado (ej: 10000ms)
• Verificar que headers default están configurados
• Verificar que NO hay URLs absolutas hardcodeadas

Archivo a revisar: apps/frontend/web/src/lib/apiClient.ts

// ✅ CORRECTO
export const apiClient = axios.create({
  baseURL: `${import.meta.env.VITE_API_URL}/api`,
  timeout: 10000,
});

// ❌ INCORRECTO
export const apiClient = axios.create({
  baseURL: 'http://localhost:3000/api',  // ❌ Hardcoded
});

---

SECCIÓN 2: DEFINICIÓN DE ENDPOINTS (FRONTEND)

2.1. Services de API

• Verificar que endpoints NO incluyen prefijo /api
• Verificar que endpoints comienzan con /
• Verificar que NO hay trailing slashes innecesarios
• Verificar que NO hay URLs completas (solo paths relativos)
• Verificar que parámetros dinámicos usan template literals correctamente

Archivos a revisar: apps/frontend/web/src/services/*.ts

// ✅ CORRECTO
export const healthService = {
  async checkHealth() {
    const response = await apiClient.get('/health');  // ✅
    return response.data;
  },
};

// ❌ INCORRECTO
export const healthService = {
  async checkHealth() {
    const response = await apiClient.get('/api/health');  // ❌ Duplica /api
    return response.data;
  },
};

2.2. Endpoints con Parámetros

• Verificar que IDs se pasan como parámetros de ruta
• Verificar que query params usan objeto params
• Verificar que template literals tienen validación
• Verificar que NO hay concatenación de strings insegura

// ✅ CORRECTO
async findById(id: string) {
  const response = await apiClient.get(`/users/${id}`);
  return response.data;
}

async searchUsers(query: string, page: number) {
  const response = await apiClient.get('/users', {
    params: { q: query, page },  // ✅ Query params
  });
  return response.data;
}

// ❌ INCORRECTO
async findById(id: string) {
  const response = await apiClient.get('/users?id=' + id);  // ❌ Concatenación
  return response.data;
}

2.3. Manejo de Respuestas

• Verificar que se retorna response.data
• Verificar que hay manejo de errores apropiado
• Verificar que tipos de respuesta están definidos
• Verificar que NO se exponen errores internos al usuario

// ✅ CORRECTO
export const userService = {
  async findById(id: string): Promise<User> {
    try {
      const response = await apiClient.get<User>(`/users/${id}`);
      return response.data;
    } catch (error) {
      console.error('[UserService] Error fetching user:', error);
      throw new Error('Failed to fetch user');
    }
  },
};

---

SECCIÓN 3: CONTROLADORES (BACKEND)

3.1. Decoradores de Controlador

• Verificar que @Controller() NO incluye prefijo /api
• Verificar que ruta del controlador es singular o plural consistente
• Verificar que decoradores de método están correctos
• Verificar que NO hay rutas hardcodeadas

Archivos a revisar: apps/backend/src/modules/*/controllers/*.controller.ts

// ✅ CORRECTO
@Controller('health')  // ✅ Sin /api
export class HealthController {
  @Get()              // GET /api/health
  @Get('database')    // GET /api/health/database
}

// ❌ INCORRECTO
@Controller('api/health')  // ❌ Genera /api/api/health
export class HealthController {
  // ...
}

@Controller('/health')     // ❌ / inicial innecesario
export class HealthController {
  // ...
}

3.2. Métodos de Controlador

• Verificar que decoradores HTTP son correctos (@Get, @Post, etc.)
• Verificar que parámetros usan decoradores apropiados (@Param, @Query, @Body)
• Verificar que tipos de respuesta están definidos
• Verificar que hay validación de DTOs

// ✅ CORRECTO
@Controller('users')
export class UsersController {
  @Get(':id')
  async findOne(@Param('id') id: string): Promise<User> {
    return this.usersService.findById(id);
  }

  @Post()
  async create(@Body() dto: CreateUserDto): Promise<User> {
    return this.usersService.create(dto);
  }

  @Get()
  async findAll(@Query('page') page: number = 1): Promise<User[]> {
    return this.usersService.findAll(page);
  }
}

3.3. Prefijo Global

• Verificar que app.setGlobalPrefix('api') está en main.ts
• Verificar que prefijo es consistente en toda la aplicación
• Verificar que NO hay múltiples prefijos globales

Archivo a revisar: apps/backend/src/main.ts

// ✅ CORRECTO
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.setGlobalPrefix('api');  // ✅ Prefijo global
  await app.listen(3000);
}

---

SECCIÓN 4: CORS Y SEGURIDAD

4.1. Configuración CORS

• Verificar que CORS está habilitado
• Verificar que origin usa variable de entorno
• Verificar que métodos permitidos son apropiados
• Verificar que headers permitidos incluyen los necesarios
• Verificar que credentials: true si se usan cookies

// ✅ CORRECTO
app.enableCors({
  origin: process.env.FRONTEND_URL || 'http://localhost:5173',
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
  allowedHeaders: ['Content-Type', 'Authorization'],
});

4.2. Autenticación

• Verificar que token se envía en header Authorization
• Verificar que interceptor agrega token automáticamente
• Verificar que hay manejo de token expirado (401)
• Verificar que NO se guarda token en localStorage si no es necesario

// ✅ CORRECTO
apiClient.interceptors.request.use((config) => {
  const token = localStorage.getItem('auth_token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

apiClient.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      // Redirect to login
      window.location.href = '/login';
    }
    return Promise.reject(error);
  }
);

---

SECCIÓN 5: TESTING

5.1. Tests de Servicios (Frontend)

• Verificar que hay tests para cada método de servicio
• Verificar que se mockea apiClient
• Verificar que se validan endpoints correctos
• Verificar que se validan parámetros y body

// ✅ CORRECTO
describe('healthService', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('should call correct endpoint', async () => {
    const getSpy = jest.spyOn(apiClient, 'get').mockResolvedValue({
      data: { status: 'ok' },
    });

    await healthService.checkHealth();

    expect(getSpy).toHaveBeenCalledWith('/health');  // ✅ Validar endpoint
  });
});

5.2. Tests de Controladores (Backend)

• Verificar que hay tests para cada endpoint
• Verificar que se validan rutas correctas
• Verificar que se validan status codes
• Verificar que se validan respuestas

// ✅ CORRECTO
describe('HealthController', () => {
  it('GET /api/health should return health status', async () => {
    const response = await request(app.getHttpServer())
      .get('/api/health')  // ✅ Ruta completa con /api
      .expect(200);

    expect(response.body).toHaveProperty('status');
  });
});

5.3. Tests E2E

• Verificar que hay tests E2E para flujos críticos
• Verificar que tests validan URLs completas
• Verificar que NO hay URLs hardcodeadas en tests
• Verificar que tests usan variables de entorno

---

SECCIÓN 6: VALIDACIÓN EN BROWSER

6.1. Network Tab

• Abrir DevTools > Network tab
• Ejecutar request que se está revisando
• Verificar que URL final NO tiene /api/api/
• Verificar que status code es correcto (200, 201, etc.)
• Verificar que response body es correcto
• Verificar que headers incluyen Authorization si es necesario

Ejemplo de validación:

Request URL: http://localhost:3000/api/health  ✅
Request Method: GET
Status Code: 200 OK

6.2. Console Logs

• Verificar que NO hay errores en consola
• Verificar que logs de API son correctos
• Verificar que NO hay warnings de CORS
• Verificar que NO hay errores 404

// Logs esperados en desarrollo
[API] GET /health
[API] Response: { status: 'ok' }

---

SECCIÓN 7: DOCUMENTACIÓN

7.1. Comentarios en Código

• Verificar que servicios tienen JSDoc
• Verificar que endpoints están documentados
• Verificar que parámetros están explicados
• Verificar que respuestas esperadas están documentadas

// ✅ CORRECTO
/**
 * Health Service
 * Handles health check endpoints
 */
export const healthService = {
  /**
   * Check API health status
   * @returns Promise<HealthStatus>
   * @endpoint GET /api/health
   */
  async checkHealth(): Promise<HealthStatus> {
    const response = await apiClient.get<HealthStatus>('/health');
    return response.data;
  },
};

7.2. README y Docs

• Verificar que endpoints están documentados en README
• Verificar que ejemplos de uso son correctos
• Verificar que variables de entorno están listadas
• Verificar que setup instructions son actuales

---

SECCIÓN 8: CONSISTENCIA

8.1. Backend ↔ Frontend

• Verificar que rutas de backend coinciden con frontend
• Verificar que DTOs son consistentes
• Verificar que tipos de respuesta coinciden
• Verificar que manejo de errores es consistente

Tabla de verificación:

Backend	Frontend	Status
GET /api/health	apiClient.get('/health')	✅
GET /api/health/database	apiClient.get('/health/database')	✅
GET /api/users/:id	apiClient.get(/users/${id})	✅

8.2. Nombrado

• Verificar que nombres de servicios siguen convención
• Verificar que nombres de controladores siguen convención
• Verificar que nombres de métodos son descriptivos
• Verificar que nombres de archivos son consistentes

Referencia: ESTANDARES-NOMENCLATURA.md

---

CHECKLIST RESUMIDO (QUICK CHECK)

Para Reviewers: Mínimo Obligatorio

Frontend:

• NO hay /api en endpoints de servicios
• baseURL usa variable de entorno
• Hay manejo de errores

Backend:

• @Controller() NO incluye /api
• Prefijo global está en main.ts
• CORS está configurado

Testing:

• Probar en Network tab del navegador
• Verificar URL final correcta
• Verificar status 200 OK

General:

• NO hay URLs hardcodeadas
• Documentación actualizada
• Tests pasan

---

PROCESO DE REVISIÓN

1. Pre-Review (Autor del PR)

Antes de crear el PR, ejecutar:

# 1. Linter
npm run lint

# 2. Tests
npm run test

# 3. Build
npm run build

# 4. Verificar archivos modificados
git diff --name-only main

2. Code Review (Reviewer)

1. Leer descripción del PR

   • Entender qué endpoints se agregaron/modificaron
   • Verificar que hay context sobre los cambios

2. Revisar archivos en orden:

   • Backend: main.ts → controladores → servicios
   • Frontend: apiClient.ts → servicios → componentes
   • Tests: Backend → Frontend → E2E

3. Usar este checklist como guía

4. Probar localmente:

   git checkout feature/branch-name
   npm install
   npm run dev
   # Abrir http://localhost:5173
   # Abrir DevTools > Network
   # Probar endpoints
   

5. Dejar comentarios:

   • Bloquear si hay errores críticos
   • Solicitar cambios si hay issues menores
   • Aprobar si todo está correcto

3. Post-Merge

• Verificar que CI/CD pasa
• Verificar deployment en staging
• Smoke test en staging
• Notificar al equipo de cambios en API

---

HERRAMIENTAS DE APOYO

1. VSCode Extension

// .vscode/settings.json
{
  "eslint.validate": [
    "javascript",
    "typescript"
  ],
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

2. GitHub PR Template

<!-- .github/pull_request_template.md -->

## API Changes

- [ ] Backend endpoints modified
- [ ] Frontend services modified
- [ ] Tests added/updated
- [ ] Tested in Network tab
- [ ] Documentation updated

### Endpoints Changed

List of endpoints:
- GET /api/...
- POST /api/...

### Testing

- [ ] Local testing done
- [ ] No /api/api/ duplicates
- [ ] CORS working
- [ ] All tests pass

3. Automated Checks

# .github/workflows/api-validation.yml

name: API Validation

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Check for /api/api/ duplicates
        run: |
          if grep -r "apiClient\.\(get\|post\|put\|delete\|patch\)(['\"]\/api\/" apps/frontend/; then
            echo "ERROR: Found /api prefix in endpoint"
            exit 1
          fi          

      - name: Check for hardcoded URLs
        run: |
          if grep -r "http://localhost:3000" apps/frontend/web/src --exclude-dir=node_modules; then
            echo "ERROR: Found hardcoded URL"
            exit 1
          fi          

---

REFERENCIAS

• ESTANDARES-API-ROUTES.md - Estándares de rutas API
• ESTANDARES-TESTING-API.md - Estándares de testing
• PITFALLS-API-ROUTES.md - Errores comunes
• ESTANDARES-NOMENCLATURA.md - Nomenclatura

---

Uso: Obligatorio en todos los code reviews que involucren APIs Responsable: Code reviewer asignado al PR Frecuencia: En cada PR antes de merge