Cómo Diseñar APIs REST para tu SaaS: Autenticación, Versionado y Documentación

Una API bien diseñada es una ventaja competitiva. Es la diferencia entre un SaaS que los desarrolladores aman integrar y uno que evitan. Para un SaaS B2B, la API pública es frecuentemente el canal principal de integración con los sistemas de tus clientes. Esta guía cubre las decisiones de diseño más importantes para construir una API REST que sea segura, predecible y fácil de usar.

Principios de Diseño REST para SaaS

REST no es solo "usar HTTP". Los principios que hacen una API REST verdaderamente usable:

• Recursos como sustantivos, no verbos: /users no /getUsers. Las acciones van en el método HTTP (GET, POST, PUT, PATCH, DELETE)
• Jerarquía clara: /organizations/123/members para recursos anidados, con máximo 2 niveles de anidamiento
• Consistencia absoluta: Si un campo se llama created_at en un recurso, se llama igual en todos los recursos
• Plural para colecciones: /users, /invoices, /projects — siempre en plural
• Respuestas predecibles: La misma estructura de respuesta sin importar el endpoint, incluyendo errores

Autenticación: API Keys vs OAuth 2.0

La mayoría de los SaaS necesitan soportar ambos tipos de autenticación para su API:

• API Keys: Para integraciones server-to-server. Simple, estática, ideal para webhooks y scripts de automatización. Header: Authorization: Bearer sk_live_xxxx
• OAuth 2.0: Para integraciones donde un usuario autoriza el acceso desde una aplicación de terceros. Flujo de autorización estándar con access_token y refresh_token

Para la mayoría de los SaaS B2B en etapa temprana, las API Keys son suficientes. Implementa OAuth cuando tus clientes necesiten que sus propios usuarios finales autoricen el acceso (modelo marketplace o plataforma).

Diseño de API Keys Seguras

• Formato con prefijo: sk_live_ para producción, sk_test_ para sandbox — igual que Stripe. Facilita identificar keys expuestas accidentalmente en código
• Almacenamiento: Guarda solo el hash (bcrypt o SHA-256) de la key en tu DB, nunca el valor completo. Muéstrala completa solo una vez al crearla
• Scopes: Permite crear keys con permisos limitados: read-only, write, admin. El principio de mínimo privilegio
• Revocación instantánea: El usuario debe poder revocar una key comprometida en segundos
• Rotación: Soporta el período de transición donde la key vieja y la nueva funcionan simultáneamente

Versionado de APIs

Las APIs cambian con el tiempo. El versionado evita romper las integraciones existentes cuando introduces cambios breaking.

• Versionado en la URL: /api/v1/users, /api/v2/users — el enfoque más explícito y más común
• Versionado en header: API-Version: 2024-01-01 — el enfoque de Stripe, más limpio pero menos obvio
• Cuándo crear una nueva versión: Cuando eliminas un campo, cambias el tipo de un campo existente, o cambias la semántica de un endpoint
• Deprecación: Anuncia la deprecación con al menos 6 meses de antelación, envía emails a los usuarios afectados y retorna headers de aviso (Deprecation: true)

Manejo de Errores Consistente

El manejo de errores es donde más APIs fallan. Un buen manejo de errores convierte un problema de depuración de 2 horas en 2 minutos.

• Estructura estándar: Todos los errores retornan el mismo formato JSON con error.code (machine-readable), error.message (human-readable) y error.details (array de errores de validación)
• Códigos HTTP correctos: 400 (input inválido), 401 (no autenticado), 403 (no autorizado), 404 (recurso no encontrado), 409 (conflicto), 422 (error de validación), 429 (rate limit), 500 (error interno)
• Error codes semánticos: "INSUFFICIENT_CREDITS", "RESOURCE_NOT_FOUND", "INVALID_API_KEY" — permite al cliente manejar cada caso específicamente

Paginación

Las colecciones con más de 100 elementos deben paginarse. Dos enfoques:

• Offset pagination: ?page=2&limit=25 — simple pero ineficiente para datasets grandes y con problemas de consistencia si los datos cambian entre páginas
• Cursor pagination: ?after=cursor_xyz&limit=25 — el enfoque de Stripe y GitHub, consistente y eficiente para cualquier tamaño de dataset
• Respuesta estándar: Incluye data (array), has_more (boolean) y next_cursor (string)

Documentación con OpenAPI

La documentación desactualizada es peor que no tener documentación: confunde a los usuarios. La solución es generar la documentación automáticamente del código.

• tRPC + Zod: Genera tipos TypeScript y documentación automáticamente de la definición de procedimientos
• Swagger/OpenAPI: Para APIs REST públicas, usa @asteasolutions/zod-to-openapi para generar el schema OpenAPI desde tus schemas Zod
• Scalar o Swagger UI: Renderiza la documentación interactiva donde los usuarios pueden probar endpoints directamente
• Postman Collections: Ofrece una colección descargable para que los desarrolladores puedan testear rápidamente sin leer la documentación completa

Rate Limiting por Plan

El rate limiting de API es también una herramienta de monetización en SaaS:

• Plan Starter: 100 requests/minuto, 10,000 requests/día
• Plan Pro: 500 requests/minuto, sin límite diario
• Plan Enterprise: Rate limits personalizados por SLA
• Headers de respuesta: Incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset en cada respuesta
• Implementación: Upstash Redis con sliding window algorithm via Vercel Edge Middleware

Webhooks: Tu API en Modo Push

Los webhooks permiten notificar a los sistemas de tus clientes cuando ocurren eventos en tu SaaS, sin que el cliente tenga que hacer polling constante.

• Firma HMAC: Firma cada webhook con HMAC-SHA256 usando un secret del cliente para que pueda verificar la autenticidad
• Reintentos con backoff: Reintenta webhooks fallidos con backoff exponencial (1min, 5min, 30min, 2h, 12h)
• Dashboard de eventos: Muestra al cliente el historial de webhooks enviados, su status y permite reenviar manualmente
• Idempotencia: Incluye un event_id único para que el cliente pueda deduplicar eventos recibidos más de una vez

Conclusión

Una API bien diseñada reduce el tiempo de integración de tus clientes de días a horas, reduce las solicitudes de soporte y aumenta la satisfacción. Las decisiones más importantes — autenticación, versionado, estructura de errores — deben tomarse antes de escribir el primer endpoint, porque cambiarlas después es costoso. En GENERA diseñamos e implementamos APIs REST que siguen estos estándares en todos nuestros proyectos SaaS.