API Inventory

Definición

Un API Inventory es un catálogo centralizado y legible por máquina de todas las APIs en una organización, conteniendo metadata esencial sobre cada endpoint: quién lo posee, qué hace, cómo acceder a él y su etapa actual del ciclo de vida. Piensa en él como la “fuente de verdad” que responde “¿Qué APIs tenemos?”

A diferencia de documentación estática (archivos Swagger, documentos README), un API Inventory es una base de datos viva que refleja la realidad actual. Se actualiza continuamente a través de API Discovery automatizado, registro manual y procesos de gestión del ciclo de vida. El inventario habilita gobernanza, monitoreo de seguridad y planificación arquitectónica al proporcionar una vista completa del paisaje de APIs de una organización.

Un API Inventory maduro captura no solo “este endpoint existe”, sino contexto crítico: requisitos de autenticación, clasificación de datos (¿procesa PII?), dependencias (¿qué servicios llama?), SLAs, estado de deprecación y propiedad (¿quién lo arregla cuando se rompe?).

Ejemplo

Antes del Inventario (Caos):

Desarrollador: “¿Hay una API para obtener pedidos de clientes?”
Respuesta: “¿Tal vez? Revisa Slack, pregunta al equipo de Plataforma o busca en Confluence?”
Resultado: Desarrollador construye una API duplicada porque no puede encontrar la existente

Después del Inventario (Claridad):

Desarrollador busca inventario: “pedidos de clientes”
Encuentra: GET /api/v2/orders - Propietaria: Alice, Estado: Activo, Auth: OAuth2
Resultado: Reutiliza API existente, contacta propietaria para acceso

Ejemplo del Mundo Real - Catálogo de APIs de Stripe:

{
  "endpoint": "/v1/customers",
  "method": "POST",
  "description": "Crea un nuevo objeto de cliente",
  "owner": "[email protected]",
  "status": "active",
  "version": "2023-10-16",
  "authentication": "bearer_token",
  "rateLimit": "100 requests por segundo",
  "dataClassification": "PII",
  "dependencies": ["identity-service", "billing-service"],
  "documentation": "https://stripe.com/docs/api/customers/create",
  "openapi": "https://api.stripe.com/openapi/v1/customers.yaml"
}

Analogía

El Catálogo de la Biblioteca: Una biblioteca no solo almacena libros en estantes—mantiene un sistema de catálogo (Dewey Decimal, Library of Congress). Puedes buscar por título, autor, tema o ISBN. El catálogo te dice si un libro existe, dónde encontrarlo, si está prestado y cuándo vence. Un API Inventory es este catálogo para APIs—no son las APIs mismas, sino el sistema que te ayuda a encontrarlas y entenderlas.

El Directorio del Edificio: En un gran edificio de oficinas, el directorio del lobby lista cada inquilino: en qué piso están, qué hacen, cómo contactarlos. Sin este directorio, vagarías por pisos aleatoriamente esperando encontrar la oficina correcta. Un API Inventory es este directorio para tu infraestructura de APIs.

Código de Ejemplo

Schema de Inventario (JSON):


{
  "api_inventory": {
    "total_apis": 247,
    "last_updated": "2026-01-14T10:30:00Z",
    "apis": [
      {
        "id": "api-customers-v2",
        "name": "API de Gestión de Clientes",
        "base_url": "https://api.company.com/v2/customers",
        "version": "2.1.3",
        "status": "active",
        "lifecycle_stage": "production",

        "ownership": {
          "team": "customer-platform",
          "owner": "[email protected]",
          "oncall": "pagerduty://customer-platform"
        },

        "technical": {
          "authentication": ["oauth2", "api_key"],
          "protocols": ["https", "http2"],
          "rate_limit": "1000 req/min por cliente",
          "sla": {
            "uptime": "99.9%",
            "response_time_p95": "200ms"
          }
        },

        "security": {
          "data_classification": "confidential",
          "processes_pii": true,
          "compliance": ["GDPR", "SOC2", "HIPAA"],
          "last_security_review": "2025-12-01"
        },

        "dependencies": {
          "upstream": ["identity-service", "billing-service"],
          "downstream": ["mobile-app", "web-app", "partner-portal"]
        },

        "documentation": {
          "openapi_url": "https://api.company.com/openapi/customers-v2.yaml",
          "developer_docs": "https://docs.company.com/api/customers",
          "changelog": "https://docs.company.com/api/customers/changelog"
        },

        "metrics": {
          "requests_per_day": 2400000,
          "unique_clients": 347,
          "error_rate": "0.02%"
        }
      },
      {
        "id": "api-customers-v1",
        "name": "API de Gestión de Clientes (Legacy)",
        "base_url": "https://api.company.com/v1/customers",
        "version": "1.9.2",
        "status": "deprecated",
        "lifecycle_stage": "sunset_planned",
        "sunset_date": "2026-06-30",
        "migration_guide": "https://docs.company.com/migration/v1-to-v2",

        "ownership": {
          "team": "customer-platform",
          "owner": "[email protected]",
          "note": "Solo modo mantenimiento"
        },

        "metrics": {
          "requests_per_day": 150000,
          "unique_clients": 23
        }
      }
    ]
  }
}

Actualizaciones Automatizadas de Inventario:


// Integración con Pipeline CI/CD
// Registrar automáticamente APIs durante despliegue

const inventoryClient = require('@company/api-inventory');

async function registerAPI() {
  // Extraer metadata de spec OpenAPI
  const openapi = readFile('openapi.yaml');
  const metadata = parseOpenAPI(openapi);

  // Agregar información de tiempo de despliegue
  const registration = {
    ...metadata,
    owner: process.env.TEAM_EMAIL,
    version: process.env.GIT_SHA,
    environment: process.env.DEPLOY_ENV,
    timestamp: new Date().toISOString()
  };

  // Registrar o actualizar en inventario
  const result = await inventoryClient.register(registration);

  if (!result.success) {
    // Bloquear despliegue si registro falla
    throw new Error('Registro de API falló - despliegue bloqueado');
  }

  console.log(`API registrada: ${result.api_id}`);
}

// Ejecutar durante despliegue
registerAPI();

Diagrama

graph TB
    A[API Inventory] --> B[Fuentes de Descubrimiento]
    B --> B1[Logs de API Gateway]
    B --> B2[Repositorios de Código]
    B --> B3[Escaneos de Infraestructura]
    B --> B4[Registro Manual]

    A --> C[Metadata]
    C --> C1[Propiedad]
    C --> C2[Detalles Técnicos]
    C --> C3[Clasificación de Seguridad]
    C --> C4[Dependencias]

    A --> D[Consumidores]
    D --> D1[Desarrolladores: Encontrar APIs]
    D --> D2[Seguridad: Auditar Superficie]
    D --> D3[Arquitectos: Planear Cambios]
    D --> D4[Cumplimiento: Generar Reportes]

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

Metadata Requerida

Inventario Mínimo Viable (debe tener):

URL del Endpoint: ¿Dónde está?
Propietario: ¿Quién es responsable?
Estado: ¿Activo, deprecado, sunset?
Autenticación: ¿Cómo se autentican los clientes?

Inventario Listo para Producción (debería tener): 5. Descripción: ¿Qué hace? 6. Versión: ¿Qué versión es esta? 7. Link de documentación: ¿Dónde aprender más? 8. Clasificación de datos: ¿Qué nivel de sensibilidad?

Inventario Maduro (completo): 9. Dependencias: ¿Qué llama? ¿Qué lo llama? 10. SLAs: Garantías de uptime, latencia 11. Rate limits: Reglas de throttling 12. Cumplimiento: Requisitos regulatorios 13. Etapa del ciclo de vida: Desarrollo, producción, deprecado 14. Métricas: Estadísticas de uso, tasas de error

Errores Comunes

Error 1: Hoja de cálculo Excel estática Un archivo Excel actualizado trimestralmente no es un inventario—es documentación desactualizada. Los inventarios deben ser automatizados y en tiempo real.

Error 2: Demasiada metadata requerida Si registrar una API requiere llenar 50 campos, los desarrolladores evitarán el proceso. Comienza mínimo, expande gradualmente.

Error 3: Sin aplicación Si el registro de API es opcional, tu inventario estará incompleto. Integra con CI/CD para forzar registro antes del despliegue.

Error 4: Inventario sin descubrimiento Solo el registro manual pierde Shadow APIs. Combina registro manual con descubrimiento automatizado para encontrar endpoints no documentados.

Error 5: Sin responsabilidad de propiedad “Equipo de plataforma” como propietario no significa nada. Cada API necesita una persona específica con información de contacto.

Inventario vs Catálogo

Aspecto	Inventario	Catálogo
Propósito	Gobernanza & cumplimiento	Experiencia de desarrollador
Audiencia	Seguridad, arquitectos, cumplimiento	Desarrolladores, partners
Contenido	Todas las APIs (incluso internas/no documentadas)	APIs curadas, publicadas
Metadata	Técnica, seguridad, cumplimiento	Ejemplos de uso, tutoriales
Automatización	Impulsado por descubrimiento	Impulsado por documentación

Relación: Inventario es la lista completa; Catálogo es el subconjunto público. Piensa: Inventario = todos los libros que posee la biblioteca (incluyendo dañados/archivados). Catálogo = libros disponibles para préstamo.

Mejores Prácticas

Automatizar descubrimiento: No depender solo de registro manual
Comenzar mínimo: Capturar endpoint, propietario, estado. Agregar más metadata después
Forzar en CI/CD: Bloquear despliegues que no se registran
Fuente única de verdad: Una herramienta de inventario, no múltiples hojas de cálculo
Hacerlo buscable: Desarrolladores deberían encontrar APIs en segundos
Mantenerlo actualizado: Actualizaciones automatizadas, no revisiones manuales trimestrales
Enlazar a docs: Inventario apunta a documentación detallada, no la reemplaza

Herramientas para API Inventory

Open Source / DIY:

Backstage (Spotify): Portal de desarrollador con plugin de catálogo de APIs
Base de datos personalizada: PostgreSQL + scripts de API Discovery
Basado en Git: Archivos YAML en repositorio con validación CI

Plataformas Empresariales:

Postman Private API Network: Catálogo de APIs de equipo con funciones de colaboración
Azure API Center: Solución de inventario de APIs centralizado de Microsoft
SwaggerHub: Plataforma de diseño de APIs con capacidades de inventario
Apigee API Hub: Gestión y catálogo de APIs de Google Cloud

Especializadas:

Akto: API Discovery + Inventory con enfoque en seguridad
42Crunch: Plataforma de seguridad de APIs con inventario integrado
Salt Security: Inventario de APIs en tiempo real desde análisis de tráfico

Hoja de Ruta de Implementación

Fase 1: Fundación (Mes 1)

Elegir herramienta/plataforma de inventario
Definir schema de metadata mínima (5-7 campos requeridos)
Registrar manualmente las 20 APIs más críticas
Crear interfaz de búsqueda para desarrolladores

Fase 2: Integración de Descubrimiento (Mes 2-3)

Configurar API Discovery automatizado (tráfico + código + infraestructura)
Importar APIs descubiertas al inventario
Asignar propietarios a todas las APIs descubiertas
Reconciliar: documentadas vs descubiertas

Fase 3: Automatización (Mes 4-6)

Integrar registro de inventario en pipeline CI/CD
Bloquear despliegues sin registro
Verificaciones automatizadas de cumplimiento (procesamiento PII sin tag GDPR = despliegue bloqueado)
Dashboard mostrando métricas de salud de inventario

Fase 4: Gobernanza (Mes 6+)

Revisiones trimestrales: remover APIs desmanteladas
Auditorías de propiedad: reasignar cuando empleados se van
Revisiones de seguridad: señalar APIs sin revisiones recientes
Analytics: APIs más usadas, candidatas a deprecación

Evaluación

Niveles de Madurez de Inventario:

Nivel 0 - Ninguno: “No sabemos qué APIs tenemos”

Nivel 1 - Estático: Hoja de cálculo Excel, actualizada manualmente

Nivel 2 - Semi-Automatizado: Base de datos con registro manual + auditorías de descubrimiento trimestrales

Nivel 3 - Automatizado: Descubrimiento en tiempo real, integración CI/CD, registro forzado

Nivel 4 - Gobernado: Automatizado + gestión de ciclo de vida + automatización de cumplimiento

Usa la Herramienta de Detección de Shadow APIs para evaluar tu nivel de madurez actual.

Lectura Adicional

📚 Libro: “Cómo Identificar Shadow APIs Con Herramientas Open Source”

Cobertura completa de implementación de API Inventory:

🇬🇧 Edición en Inglés
🇪🇸 Edición en Español

Capítulos clave:

Capítulo 4: Construcción de Tu Primer API Inventory (diseño de schema, herramientas)
Capítulo 6: Marcos de Gobernanza (cómo el inventario habilita gobernanza)
Capítulo 7: Pipeline Automatizado Descubrimiento → Inventario
Capítulo 10: Medición de Completitud y Precisión del Inventario