Catálogo de APIs

Definición

Un Catálogo de APIs es un directorio curado y orientado a desarrolladores de APIs disponibles diseñado para ayudar a desarrolladores internos, partners o consumidores externos a descubrir e integrar con APIs rápidamente. A diferencia de un Inventario de APIs (que rastrea todas las APIs para gobernanza), un Catálogo presenta APIs publicadas con documentación rica, ejemplos de uso y guías de onboarding.

Piensa en el Catálogo como un escaparate de productos: presenta APIs como productos que los desarrolladores quieren usar, completo con guías de “primeros pasos”, ejemplos de código, instrucciones de autenticación y herramientas de testing interactivas. El objetivo es la experiencia del desarrollador (DX), no el cumplimiento—hacer fácil encontrar, entender e integrar con APIs.

Un buen Catálogo de APIs responde: “¿Qué puedo construir con estas APIs?” mientras que un Inventario responde “¿Qué APIs existen y quién las posee?” Ambos son esenciales pero sirven propósitos diferentes.

Ejemplo

Catálogo de APIs de Stripe:

La referencia pública de APIs de Stripe (https://stripe.com/docs/api) es un Catálogo de APIs ejemplar:

Buscable: Escribe “payment” y encuentra endpoints relevantes instantáneamente
Interactivo: Prueba llamadas de API directamente desde la documentación con claves API reales
Ejemplos de código: Cada endpoint muestra ejemplos en curl, Python, Ruby, Node.js
Organizado por caso de uso: “Aceptar un pago”, “Crear un cliente”, “Emitir un reembolso”
Versionado: Ver documentación para la versión actual + versiones históricas

Catálogo de APIs de Twilio:

Twilio organiza su catálogo por producto (SMS, Voice, Video), facilitando encontrar APIs relevantes para tu caso de uso. Cada API incluye:

Guías de inicio rápido (“Envía tu primer SMS en 5 minutos”)
SDKs para 7+ lenguajes
Información de límites de tasa y precios
Aplicaciones de ejemplo que puedes desplegar inmediatamente

Ejemplo de Catálogo Interno:

El portal de desarrollador interno de una empresa podría catalogar:

API de Clientes: Gestionar perfiles de clientes y preferencias
API de Pedidos: Crear y rastrear pedidos
API de Inventario: Verificar disponibilidad de productos
API de Pagos: Procesar pagos y reembolsos

Cada entrada incluye: endpoints, método de autenticación, límites de tasa, requests/responses de ejemplo e información de contacto del equipo propietario.

Analogía

El Menú del Restaurante: Un Catálogo de APIs es como un menú de restaurante. El menú no lista todo lo que la cocina puede hacer (eso es el inventario)—muestra lo que está disponible para clientes ahora mismo, con descripciones, precios e imágenes. El menú está diseñado para que los clientes tomen decisiones rápidamente (“Quiero la pasta”). Similarmente, un Catálogo de APIs muestra a los desarrolladores qué está disponible y les ayuda a elegir la API correcta para sus necesidades.

La Sala de Exhibición de Productos: IKEA no te muestra todo su inventario de almacén—crean salas de exhibición mostrando configuraciones de habitaciones terminadas para que puedas imaginar cómo funcionan los productos juntos. Un Catálogo de APIs es esta sala de exhibición: curado, organizado y diseñado para descubrimiento, no auditoría comprehensiva.

Ejemplo de Código

Entrada de Catálogo de APIs (YAML):


# catalog-entry.yaml
# Ejemplo de entrada de catálogo para API de Clientes

api:
  id: "customers-api-v2"
  name: "API de Gestión de Clientes"
  version: "2.1.0"
  status: "stable"
  tagline: "Gestiona perfiles de clientes, preferencias y detalles de cuenta"

  # Información orientada a desarrolladores
  getting_started:
    quickstart_url: "https://docs.company.com/quickstart/customers"
    estimated_time: "10 minutos"
    prerequisites:
      - "Credenciales de cliente OAuth2"
      - "Comprensión básica de REST APIs"

  # Detalles de la API
  base_url: "https://api.company.com/v2/customers"
  authentication:
    - type: "oauth2"
      scopes: ["customers:read", "customers:write"]
    - type: "api_key"
      note: "Obsoleto, usa OAuth2 para nuevas integraciones"

  rate_limits:
    - tier: "free"
      limit: "100 solicitudes/hora"
    - tier: "paid"
      limit: "10,000 solicitudes/hora"

  # Documentación
  documentation:
    overview: "https://docs.company.com/api/customers"
    openapi_spec: "https://api.company.com/openapi/customers-v2.yaml"
    interactive_docs: "https://api.company.com/swagger-ui/customers"
    changelog: "https://docs.company.com/changelog/customers"

  # Ejemplos de Código
  code_samples:
    - language: "curl"
      example: |
        curl -X GET "https://api.company.com/v2/customers/cust_123" \
          -H "Authorization: Bearer YOUR_TOKEN"

    - language: "javascript"
      example: |
        const customer = await fetch('https://api.company.com/v2/customers/cust_123', {
          headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
        }).then(r => r.json());

    - language: "python"
      example: |
        import requests
        response = requests.get(
          'https://api.company.com/v2/customers/cust_123',
          headers={'Authorization': 'Bearer YOUR_TOKEN'}
        )
        customer = response.json()

  # Soporte
  support:
    team: "Customer Platform Team"
    email: "[email protected]"
    slack: "#api-customers"
    oncall: "pagerduty://customer-platform"

  # Casos de Uso Comunes
  use_cases:
    - title: "Crear una nueva cuenta de cliente"
      endpoint: "POST /v2/customers"
      doc_link: "https://docs.company.com/tutorials/create-customer"

    - title: "Actualizar preferencias de cliente"
      endpoint: "PATCH /v2/customers/{id}/preferences"
      doc_link: "https://docs.company.com/tutorials/customer-preferences"

    - title: "Buscar clientes por email"
      endpoint: "GET /v2/customers?email={email}"
      doc_link: "https://docs.company.com/tutorials/search-customers"

  # APIs Relacionadas
  related_apis:
    - "orders-api-v2"
    - "payments-api-v2"
    - "notifications-api-v1"

Diagrama

graph TB
    A[Catálogo de APIs] --> B[UI Portal de Desarrolladores]
    A --> C[Búsqueda y Descubrimiento]
    A --> D[Documentación]
    A --> E[Herramientas Interactivas]

    B --> B1[Listados Categorizados]
    B --> B2[APIs Populares]
    B --> B3[Recientemente Actualizadas]

    C --> C1[Búsqueda Full-Text]
    C --> C2[Filtrado por Tags]
    C --> C3[Navegación por Caso de Uso]

    D --> D1[Guías de Inicio]
    D --> D2[Referencia de API]
    D --> D3[Ejemplos de Código]
    D --> D4[Tutoriales]

    E --> E1[Explorador Interactivo de API]
    E --> E2[Probar Ahora]
    E --> E3[Generadores de Código]

    F[Audiencia Objetivo] --> F1[Desarrolladores Internos]
    F --> F2[Integradores Partners]
    F --> F3[Consumidores Externos]

    F1 --> B
    F2 --> B
    F3 --> B

    style A fill:#bbdefb
    style B fill:#c8e6c9
    style D fill:#fff9c4
    style E fill:#e1bee7

Catálogo vs Inventario

Aspecto	Catálogo de APIs	Inventario de APIs
Propósito	Experiencia del desarrollador	Gobernanza y cumplimiento
Audiencia	Desarrolladores, partners	Seguridad, arquitectos, cumplimiento
Contenido	APIs publicadas y estables	Todas las APIs (incluyendo Shadow, Zombie)
Curación	Altamente curado	Comprehensivo (sin curación)
Metadata	Ejemplos de uso, tutoriales	Propietario, estado, tags de cumplimiento
Frecuencia de actualización	Cuando APIs cambian	Tiempo real (descubrimiento automatizado)
Enfoque	“¿Cómo uso esto?”	“¿Qué existe y quién lo posee?”

Ambos son esenciales: Inventario para gobernanza, Catálogo para productividad del desarrollador.

Características Esenciales del Catálogo

1. Búsqueda y Descubrimiento

Búsqueda full-text en nombres de APIs, descripciones y endpoints
Filtrado basado en tags (“muéstrame todas las APIs de pago”)
Organización por caso de uso ("¿Cómo envío un email?")

2. Documentación Rica

Guía de inicio (quickstart de 5-10 minutos)
Referencia completa de API (todos los endpoints)
Instrucciones de autenticación con ejemplos
Límites de tasa y manejo de errores

3. Testing Interactivo

Funcionalidad “Probar ahora” (Swagger UI, Stoplight, Postman)
Requests de ejemplo prellenados
Testing contra entornos sandbox

4. Ejemplos de Código

Ejemplos en 3-5 lenguajes (curl, JavaScript, Python, Java, etc.)
Snippets listos para copiar-pegar
Documentación completa de SDK si está disponible

5. Versionado

Versión actual claramente marcada
Documentación de versiones históricas disponible
Guías de migración entre versiones

6. Información de Soporte

Contacto del equipo propietario (email, Slack, PagerDuty)
Problemas conocidos y página de estado
Changelog y notas de versión

Errores Comunes

Error 1: Catálogo = spec Swagger/OpenAPI Un spec OpenAPI es una referencia, no un catálogo. Los desarrolladores necesitan tutoriales, ejemplos y orientación de casos de uso, no solo definiciones de endpoints.

Error 2: Incluir APIs internas/obsoletas Un Catálogo debe estar curado. No listes cada API—solo las que quieres que los desarrolladores usen. Las APIs obsoletas van en una sección “Legacy” con guías de migración.

Error 3: Sin funcionalidad de búsqueda Si los desarrolladores no pueden encontrar APIs rápidamente, construirán duplicados. La búsqueda debe ser rápida y comprehensiva.

Error 4: Documentación sin ejemplos “Este endpoint acepta un body JSON” es inútil. Muestra un ejemplo real: {"name": "John Doe", "email": "[email protected]"}.

Error 5: Información desactualizada Si tu Catálogo dice que la API requiere una API key pero ha sido migrada a OAuth2, los desarrolladores fallarán al autenticarse. Mantén el Catálogo sincronizado con la realidad.

Mejores Prácticas

Actualizar automáticamente: Genera Catálogo desde specs OpenAPI + metadata, no mantengas manualmente
Organizar por caso de uso: “Cómo enviar notificaciones” es mejor que lista alfabética de APIs
Destacar APIs populares: Mostrar secciones “Más usadas” o “Recientemente actualizadas”
Proporcionar sandboxes: Permitir a desarrolladores probar sin afectar producción
Incluir límites de tasa: Los desarrolladores necesitan conocer cuotas de antemano
Enlazar a soporte: Cada API debe tener un canal de soporte claro
Medir uso: Rastrear qué APIs se buscan más, qué docs se ven más

Herramientas para Catálogos de APIs

Open Source:

Backstage (Spotify)

Portal de desarrolladores con plugin de API
Personalizable, extensible
Integración con pipelines CI/CD

Swagger UI

Documentación interactiva de APIs
Se genera automáticamente desde specs OpenAPI
Funcionalidad probar-ahora

Stoplight

Plataforma de documentación de APIs
Servidores mock y testing
Edición colaborativa

Comercial:

Postman Workspaces

Colaboración en equipo en APIs
Catálogo privado de APIs
Testing y monitoreo

SwaggerHub

Diseño y documentación de APIs
Colaboración en equipo
SDKs de cliente auto-generados

Azure API Center

Catálogo centralizado para APIs de Azure
Descubrimiento y gobernanza
Integración con Azure API Management

ReadMe

Plataforma de documentación para desarrolladores
Explorador interactivo de APIs
Métricas y analytics

Tips de Implementación

Fase 1: Catálogo Mínimo (Semana 1)

Listar 10-20 APIs más importantes
Incluir: nombre, descripción, enlace a spec OpenAPI, contacto del propietario
Desplegar a wiki interna o Confluence

Fase 2: Catálogo Rico (Mes 1)

Agregar guías de inicio para top 5 APIs
Incluir ejemplos de código (curl, JavaScript, Python)
Implementar funcionalidad de búsqueda

Fase 3: Catálogo Interactivo (Mes 2-3)

Desplegar Swagger UI o Stoplight
Agregar funcionalidad probar-ahora
Crear entornos sandbox

Fase 4: Catálogo Pulido (Mes 3+)

Organización por caso de uso
Video tutoriales para APIs complejas
Métricas: rastrear queries de búsqueda, APIs populares

Ejemplo: Experiencia del Desarrollador de Stripe

Por qué el Catálogo de Stripe destaca:

Onboarding sin fricción: Crear cuenta → Obtener API key → Hacer primer request en <5 minutos
Testing interactivo: Probar cada endpoint directamente desde docs
Docs específicos por lenguaje: Alternar entre curl, Python, Ruby, Node.js, PHP, Go, .NET
Testing en tiempo real: Probar con claves reales contra modo test
Ejemplos comprehensivos: No solo “crear un pago” sino “crear un pago con autenticación 3D Secure”
Dashboard de estado: Monitoreo de salud de API en tiempo real

Resultado: Los desarrolladores aman las APIs de Stripe debido a la documentación. El Catálogo es una ventaja competitiva.

Lectura Adicional

Mejores Prácticas de Documentación de APIs:

Conceptos Relacionados:

Herramientas Mencionadas: