Diseño de APIs

¿Qué es?

El diseño de APIs es la disciplina de crear interfaces programáticas que sean claras, consistentes y evolucionables. Una API bien diseñada actúa como un contrato entre sistemas, definiendo cómo los consumidores pueden interactuar con un servicio de manera predecible y confiable.

El diseño efectivo de APIs va más allá de simplemente exponer funcionalidad. Requiere considerar la experiencia del desarrollador, la evolución del sistema a largo plazo, y la integración con patrones arquitectónicos como microservicios y API Gateway. Una API bien diseñada reduce la fricción en la adopción, minimiza los errores de integración, y permite que los equipos trabajen de manera independiente.

El proceso de diseño debe ser iterativo y centrado en el usuario, comenzando con la definición del contrato antes de la implementación — un enfoque conocido como API-first que se alinea con el desarrollo dirigido por especificaciones.

Estilos arquitectónicos

Especificación OpenAPI

Una especificación OpenAPI define el contrato de una API REST de manera declarativa. Ejemplo para un endpoint de usuarios:

openapi: 3.0.3
info:
  title: User Management API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/CursorPagination'
components:
  schemas:
    User:
      type: object
      required: [id, email, created_at]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        created_at:
          type: string
          format: date-time
    CursorPagination:
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean

Estrategias de versionado

Patrones de paginación

Cursor-based (recomendado)

{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIzfQ==",
    "has_more": true,
    "limit": 20
  }
}

Ventajas: Consistente con datos cambiantes, eficiente para datasets grandes Desventajas: No permite saltar a páginas específicas

Offset-based

{
  "data": [...],
  "pagination": {
    "offset": 40,
    "limit": 20,
    "total": 1250,
    "has_more": true
  }
}

Ventajas: Familiar, permite navegación directa Desventajas: Inconsistente con inserciones/eliminaciones, ineficiente en datasets grandes

Estándares de respuesta de error

Siguiendo RFC 9457 (Problem Details for HTTP APIs), que reemplaza al RFC 7807:

{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request body contains invalid data",
  "instance": "/users/create",
  "errors": [
    {
      "field": "email",
      "code": "INVALID_FORMAT",
      "message": "Email must be a valid email address"
    }
  ],
  "trace_id": "abc123def456"
}

Diseño de rate limiting

Estrategias comunes

Headers de respuesta

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 742
X-RateLimit-Reset: 1640995200
Retry-After: 3600

Seguridad y autenticación

La integración con OAuth/OIDC es fundamental para APIs modernas. Consideraciones clave:

• Bearer tokens para autenticación stateless
• Scopes granulares para autorización específica
• HTTPS obligatorio en producción
• Validación de input en todos los endpoints
• Rate limiting por usuario/IP

Observabilidad integrada

Las APIs deben integrarse nativamente con la observabilidad:

• Trace IDs en headers de respuesta
• Métricas de latencia por endpoint
• Logs estructurados con contexto de request
• Health checks estandarizados (/health, /ready)

¿Por qué importa?

Una API mal diseñada se convierte en deuda técnica permanente. Cada decisión de diseño — nomenclatura de recursos, estructura de respuestas, manejo de errores — se solidifica una vez que hay consumidores en producción. Cambiar una API pública requiere versionado, migración de clientes, y coordinación entre equipos.

El costo de rediseñar una API después del lanzamiento es exponencialmente mayor que invertir en diseño inicial. Una API bien diseñada reduce el tiempo de integración de semanas a días, minimiza tickets de soporte, y permite que los equipos de producto se muevan más rápido. En organizaciones con múltiples equipos, las APIs consistentes reducen la carga cognitiva y permiten reutilización de herramientas y patrones.

Referencias

• API Design Patterns — JJ Geewax, Manning, 2021. Patrones comprobados para diseño de APIs.
• OpenAPI Specification 3.1.0 — OpenAPI Initiative, 2021. Estándar para especificación de APIs REST.
• RFC 9457: Problem Details for HTTP APIs — IETF, 2023. Estándar actual para respuestas de error estructuradas (reemplaza RFC 7807).
• Google API Design Guide — Google, 2024. Guía completa de mejores prácticas para APIs.
• REST API Design Rulebook — Mark Masse, O'Reilly, 2011. Principios fundamentales de diseño REST.
• Build APIs You Won't Hate — Phil Sturgeon, 2015. Guía práctica para diseño de APIs centrado en desarrolladores.