Construyendo APIs de nivel producción: la guía de ingeniería completa

Las APIs son productos

Las mejores APIs del mundo — Stripe, Twilio, GitHub — a menudo se citan como mejores productos que la propia interfaz de usuario de la empresa. Esto no es casualidad. Estas empresas tratan sus APIs como productos de primera clase con el mismo cuidado por la experiencia del desarrollador que dan a sus interfaces.

Esta guía cubre las prácticas de ingeniería que separan las APIs de nivel producción del resto.

Principios de diseño de API

REST vs. GraphQL vs. gRPC

Elige el protocolo correcto para tu caso de uso:

Nomenclatura y estructura

Un buen diseño de API es aburrido. Sigue convenciones establecidas para que los desarrolladores puedan predecir el comportamiento sin leer la documentación.

✅ Buen diseño de API REST:
GET    /api/v1/users              # Listar usuarios
POST   /api/v1/users              # Crear usuario
GET    /api/v1/users/{id}         # Obtener usuario
PUT    /api/v1/users/{id}         # Reemplazar usuario
PATCH  /api/v1/users/{id}         # Actualizar usuario
DELETE /api/v1/users/{id}         # Eliminar usuario
GET    /api/v1/users/{id}/orders  # Obtener pedidos del usuario

❌ Errores comunes:
GET    /getUser?userId=123
POST   /api/createNewUser
GET    /api/fetchUserOrders/{userId}

Autenticación y autorización

Mejores prácticas de JWT

import jwt from 'jsonwebtoken';

// ✅ Tokens de acceso de corta duración + tokens de actualización
const ACCESS_TOKEN_EXPIRY = '15m';
const REFRESH_TOKEN_EXPIRY = '7d';

function generateTokenPair(userId: string) {
  const accessToken = jwt.sign(
    { sub: userId, type: 'access' },
    process.env.JWT_SECRET!,
    { expiresIn: ACCESS_TOKEN_EXPIRY }
  );

  const refreshToken = jwt.sign(
    { sub: userId, type: 'refresh', jti: crypto.randomUUID() },
    process.env.REFRESH_SECRET!,
    { expiresIn: REFRESH_TOKEN_EXPIRY }
  );

  return { accessToken, refreshToken };
}

Limitación de tasa

La limitación de tasa protege tu API del abuso y garantiza un uso justo. Impleméntala en múltiples niveles:

1. Limitación a nivel de IP: prevenir ataques DoS
2. Limitación a nivel de usuario: aplicar un uso justo
3. Limitación a nivel de endpoint: las operaciones costosas obtienen límites más bajos

import { Ratelimit } from '@upstash/ratelimit';
import { Redis } from '@upstash/redis';

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(100, '1 m'), // 100 solicitudes por minuto
  analytics: true,
});

export async function apiMiddleware(req: Request) {
  const identifier = getClientIdentifier(req);
  const { success, limit, remaining, reset } = await ratelimit.limit(identifier);

  if (!success) {
    return new Response('Too Many Requests', {
      status: 429,
      headers: {
        'X-RateLimit-Limit': limit.toString(),
        'X-RateLimit-Remaining': remaining.toString(),
        'X-RateLimit-Reset': new Date(reset).toISOString(),
        'Retry-After': Math.ceil((reset - Date.now()) / 1000).toString(),
      },
    });
  }
}

Manejo de errores

Las respuestas de error consistentes e informativas son el sello distintivo de una gran API.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body is invalid",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "value": "not-an-email"
      }
    ],
    "requestId": "req_abc123",
    "docs": "https://api.eryon.ai/docs/errors/VALIDATION_ERROR"
  }
}

Versionado de API

Nunca rompas a tus consumidores. Versiona tu API desde el primer día.

Estrategia: versionado por ruta de URL (la más simple, la más compatible)

/api/v1/users
/api/v2/users

Reglas de versionado:

• Versión mayor (v1 → v2): cambios que rompen compatibilidad
• Versión menor: adiciones retrocompatibles
• Política de desaprobación: anunciar 6 meses antes de eliminar una versión

Las APIs en las que los desarrolladores confían — y que se convierten en fosos para tu negocio — están construidas sobre estos cimientos. Cada atajo que tomes en el diseño de API te costará diez veces más cuando necesites arreglarlo con miles de integraciones activas.