Definición
La documentación de API es la guía de referencia completa que enseña a los desarrolladores cómo usar una API. Incluye descripciones de endpoints, métodos de autenticación, schemas de petición/respuesta, ejemplos de código en múltiples lenguajes, códigos de error, límites de tasa, política de versionado y tutoriales de inicio. Una buena documentación es precisa, actualizada, buscable e incluye funcionalidad interactiva de “probar”.
A diferencia de la documentación de código interno, la documentación de API es de cara al exterior - a menudo es la primera y única interacción que los desarrolladores tienen con tu API. Si la documentación es poco clara, incompleta o incorrecta, los desarrolladores abandonan la API por la competencia. Una documentación excelente reduce tickets de soporte, acelera el tiempo de integración y aumenta la adopción de la API.
La documentación de API moderna típicamente se auto-genera desde especificaciones OpenAPI usando herramientas como Swagger UI, Redoc o Stoplight. Esto asegura que la documentación se mantenga sincronizada con la implementación real de la API. La documentación interactiva permite a los desarrolladores hacer llamadas API en vivo directamente desde el navegador, reduciendo dramáticamente el tiempo hasta la primera llamada exitosa.
Ejemplo
Documentación de Stripe: Stripe es famosa por tener documentación de API de clase mundial. Combinan documentación de referencia auto-generada desde specs OpenAPI con guías escritas a mano, tutoriales y recetas. Cada endpoint tiene ejemplos de código en más de 8 lenguajes, “probar” interactivo con claves API de prueba, y explicaciones detalladas de casos de uso.
Twilio SendGrid: La documentación de SendGrid incluye una referencia API completa, guías de inicio para diferentes lenguajes, catálogos de eventos webhook y secciones de resolución de problemas. Los desarrolladores pueden probar el envío de email directamente en la documentación sin escribir código primero.
API REST de GitHub: GitHub publica especificaciones OpenAPI completas que alimentan su documentación API interactiva. Cada endpoint incluye descripciones, parámetros, schemas de respuesta y ejemplos. También versionan la documentación - puedes ver documentación para versiones anteriores de la API.
Microservicios Internos: Una empresa con más de 50 microservicios mantiene un portal API central usando Backstage o herramientas similares. Cada servicio publica specs OpenAPI al portal, auto-generando documentación buscable. Los ingenieros descubren APIs, entienden schemas e integran servicios más rápido.
Colecciones Postman: Muchas empresas publican colecciones Postman junto a la documentación tradicional. Los desarrolladores importan la colección en Postman e inmediatamente tienen ejemplos funcionales para cada endpoint con parámetros y autenticación pre-rellenados.
Analogía
El Manual del Propietario: Así como un coche viene con un manual del propietario explicando cómo operar funcionalidades, realizar mantenimiento y resolver problemas, la documentación de API explica cómo usar las funcionalidades de la API, manejar errores y optimizar el uso. Nadie compraría un coche con un manual faltante o críptico.
El Menú del Restaurante: Un buen menú no solo lista nombres de platos - describe ingredientes, muestra fotos, nota alérgenos y sugiere maridajes. La documentación de API es lo mismo - no solo listes endpoints, muestra ejemplos, explica parámetros, nota límites de tasa y sugiere mejores prácticas.
Instrucciones de Montaje de IKEA: Las instrucciones de IKEA son famosas por una guía clara, visual y paso a paso que funciona en todos los idiomas. La documentación de API debería ser igualmente clara - diagramas visuales, tutoriales secuenciales y jerga mínima ayudan a desarrolladores independientemente de su nivel de experiencia.
Ejemplo de Código
Especificación OpenAPI con Documentación Rica
openapi: 3.1.0
info:
title: API de Procesamiento de Pagos
version: 2.0.0
description: |
Procesa pagos, gestiona reembolsos y maneja suscripciones.
## Primeros Pasos
1. Regístrate para obtener una clave API en https://example.com/signup
2. Prueba primero en modo sandbox: https://sandbox.example.com
3. Usa `Bearer TU_CLAVE_API` en el header Authorization
## Límites de Tasa
- Plan estándar: 1000 peticiones/hora
- Plan empresarial: 10000 peticiones/hora
## Soporte
- Email: [email protected]
- Slack: https://slack.example.com
contact:
name: Soporte API
email: [email protected]
url: https://example.com/support
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://api.example.com/v2
description: Servidor de producción
- url: https://sandbox.example.com/v2
description: Sandbox para pruebas
tags:
- name: Pagos
description: Crea y gestiona transacciones de pago
- name: Reembolsos
description: Procesa reembolsos para pagos completados
paths:
/payments:
post:
tags: [Pagos]
summary: Crear un pago
description: |
Crea una nueva transacción de pago. El pago se procesa de forma asíncrona.
Usa webhooks para recibir actualizaciones de estado.
**Casos de uso comunes:**
- Compras únicas
- Pagos iniciales de suscripción
- Pagos de facturas
**Notas importantes:**
- Los pagos menores a $1 USD son rechazados
- Idempotente - reintenta con la misma clave de idempotencia si la red falla
- Retorna inmediatamente con estado "pending"
operationId: createPayment
parameters:
- name: Idempotency-Key
in: header
description: |
Clave única opcional para prevenir cargos duplicados.
Usa la misma clave cuando reintentes peticiones fallidas.
required: false
schema:
type: string
format: uuid
example: "550e8400-e29b-41d4-a716-446655440000"
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentRequest'
examples:
creditCard:
summary: Pago con tarjeta de crédito
description: Cargo estándar con tarjeta de crédito
value:
amount: 99.99
currency: USD
paymentMethod:
type: credit_card
cardNumber: "4242424242424242"
expiryMonth: 12
expiryYear: 2025
cvv: "123"
description: "Pedido #12345"
savedCard:
summary: Usando método de pago guardado
description: Cargar una tarjeta previamente guardada
value:
amount: 49.99
currency: EUR
paymentMethod:
type: saved
paymentMethodId: "pm_1234567890"
description: "Renovación de suscripción"
responses:
'201':
description: |
Pago creado exitosamente. El estado es inicialmente "pending".
Suscríbete a webhooks para recibir notificaciones de completitud.
headers:
X-Request-ID:
schema:
type: string
description: ID único para rastrear esta petición
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
example:
id: "pay_1234567890"
status: "pending"
amount: 99.99
currency: "USD"
description: "Pedido #12345"
createdAt: "2024-01-15T10:30:00Z"
'400':
description: Datos de petición inválidos
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalidAmount:
summary: Cantidad demasiado baja
value:
code: "INVALID_AMOUNT"
message: "La cantidad debe ser al menos $1.00 USD"
invalidCard:
summary: Número de tarjeta inválido
value:
code: "INVALID_CARD"
message: "El número de tarjeta falló la validación"
'429':
description: Límite de tasa excedido
headers:
X-RateLimit-Limit:
schema:
type: integer
description: Peticiones permitidas por hora
X-RateLimit-Remaining:
schema:
type: integer
description: Peticiones restantes en la ventana actual
X-RateLimit-Reset:
schema:
type: integer
description: Timestamp Unix cuando se resetea el límite de tasa
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: "RATE_LIMIT_EXCEEDED"
message: "Has excedido el límite de tasa de 1000 peticiones/hora"
components:
schemas:
CreatePaymentRequest:
type: object
required: [amount, currency, paymentMethod]
properties:
amount:
type: number
minimum: 1.00
description: Cantidad de pago en la moneda especificada
example: 99.99
currency:
type: string
pattern: "^[A-Z]{3}$"
description: Código de moneda ISO 4217
example: "USD"
paymentMethod:
type: object
description: Detalles del método de pago
oneOf:
- $ref: '#/components/schemas/CreditCardPayment'
- $ref: '#/components/schemas/SavedPaymentMethod'
description:
type: string
maxLength: 500
description: Descripción opcional para tu referencia
example: "Pedido #12345"
CreditCardPayment:
type: object
required: [type, cardNumber, expiryMonth, expiryYear, cvv]
properties:
type:
type: string
const: credit_card
cardNumber:
type: string
pattern: "^[0-9]{13,19}$"
description: Número de tarjeta de crédito sin espacios
example: "4242424242424242"
expiryMonth:
type: integer
minimum: 1
maximum: 12
example: 12
expiryYear:
type: integer
minimum: 2024
example: 2025
cvv:
type: string
pattern: "^[0-9]{3,4}$"
example: "123"
SavedPaymentMethod:
type: object
required: [type, paymentMethodId]
properties:
type:
type: string
const: saved
paymentMethodId:
type: string
description: ID del método de pago previamente guardado
example: "pm_1234567890"
Payment:
type: object
properties:
id:
type: string
description: Identificador único del pago
example: "pay_1234567890"
status:
type: string
enum: [pending, completed, failed, refunded]
description: |
Estado actual del pago:
- `pending` - El pago está siendo procesado
- `completed` - El pago fue exitoso
- `failed` - El pago falló (ver failureReason)
- `refunded` - El pago fue reembolsado
amount:
type: number
example: 99.99
currency:
type: string
example: "USD"
description:
type: string
createdAt:
type: string
format: date-time
completedAt:
type: string
format: date-time
nullable: true
failureReason:
type: string
nullable: true
description: Razón legible si el estado es "failed"
Error:
type: object
required: [code, message]
properties:
code:
type: string
description: Código de error legible por máquina
example: "INVALID_AMOUNT"
message:
type: string
description: Mensaje de error legible por humanos
example: "La cantidad debe ser al menos $1.00 USD"
details:
type: object
description: Contexto adicional del error
additionalProperties: true
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: |
Usa tu clave API como token Bearer:
```
Authorization: Bearer TU_CLAVE_API
```
Obtén tu clave API desde https://example.com/dashboard/api-keys
security:
- BearerAuth: []
Diagrama
graph TB
subgraph "Componentes de Documentación de API"
SPEC[Especificación OpenAPI
Fuente Única de Verdad]
SPEC --> REF[Documentación de Referencia
Swagger UI, Redoc]
SPEC --> SDK[Documentación de SDK
Específica por Lenguaje]
GUIDES[Guías Escritas a Mano]
GUIDES --> QUICKSTART[Inicio Rápido
Primera Llamada en 5min]
GUIDES --> TUTORIALS[Tutoriales
Casos de Uso Comunes]
GUIDES --> RECIPES[Recetas
Ejemplos de Código]
EXTRA[Recursos Adicionales]
EXTRA --> ERRORS[Catálogo de Errores
Todos los Códigos Explicados]
EXTRA --> CHANGELOG[Registro de Cambios
Historial de Versiones]
EXTRA --> MIGRATION[Guías de Migración
Actualizar Versiones]
end
REF --> PORTAL[Portal de Desarrollador]
SDK --> PORTAL
QUICKSTART --> PORTAL
TUTORIALS --> PORTAL
ERRORS --> PORTAL
CHANGELOG --> PORTAL
PORTAL --> SEARCH[Buscable
Búsqueda de Texto Completo]
PORTAL --> INTERACTIVE[Interactivo
Probar Ahora]
PORTAL --> FEEDBACK[Sistema de Retroalimentación
Mejorar Documentación]
style SPEC fill:#90EE90
style PORTAL fill:#87CEEB
style INTERACTIVE fill:#FFD700
Mejores Prácticas
- Comienza con guía de inicio - Ayuda a los desarrolladores a hacer su primera llamada API exitosa en menos de 5 minutos
- Proporciona ejemplos de código - Muestra código real y funcional en múltiples lenguajes para cada endpoint
- Hazlo interactivo - Habilita funcionalidad “probar ahora” con credenciales de prueba
- Documenta errores exhaustivamente - Cada código de error con explicación, causa y solución
- Mantén sincronizado con la implementación - Auto-genera desde especificaciones OpenAPI para prevenir desincronización
- Versiona la documentación - Permite a los desarrolladores ver documentación para versiones antiguas de la API
- Incluye casos de uso del mundo real - Muestra escenarios comunes y patrones recomendados
- Hazlo buscable - Búsqueda de texto completo en toda la documentación, ejemplos y guías
Errores Comunes
Documentación desactualizada: Documentación describiendo comportamiento de API que ya no existe. Auto-genera desde especificaciones para mantenerse sincronizada.
Falta documentación de errores: Solo documentar casos exitosos, ignorando respuestas de error. Los desarrolladores necesitan saber cómo manejar fallos.
Sin ejemplos de código: Descripciones abstractas sin código concreto y funcional. Muestra ejemplos en lenguajes populares.
Asumir conocimiento: Usar jerga o asumir familiaridad con conceptos. Explica claramente para principiantes.
Sin guía de inicio: Saltar directamente a la referencia API sin un tutorial de inicio rápido. Los desarrolladores se pierden.
Solo documentación estática: Sin capacidad interactiva de “probar ahora”. Los desarrolladores tienen que configurar entornos locales antes de probar.
Ejemplos rotos: Ejemplos de código que en realidad no funcionan cuando se copian. Prueba todo el código de ejemplo.
Sin funcionalidad de búsqueda: Páginas de documentación largas sin búsqueda. Los desarrolladores no pueden encontrar lo que necesitan rápidamente.