Tu documentación de API tiene 47 endpoints listados. Cada uno tiene el método HTTP, la ruta, el cuerpo de la solicitud y el esquema de respuesta. Es completa, precisa y completamente inútil.
¿Por qué? Porque cuando llego a tu documentación, generalmente no quiero un inventario de endpoints.
Quiero completar una tarea.
Quiero saber cómo crear el cliente, adjuntar el método de pago, iniciar la suscripción, manejar el webhook, recuperarme de una falla y probarlo de forma segura.
La referencia de endpoints es necesaria. No es el producto.
La referencia no es incorporación
Una página de referencia responde:
- qué ruta existe
- qué método acepta
- qué campos están permitidos
- cómo se ve la respuesta
La incorporación responde:
- ¿qué debería hacer primero?
- ¿en qué orden ocurren estas llamadas?
- ¿qué puede fallar?
- ¿qué debería almacenar?
- ¿cómo pruebo esto sin romper producción?
Si tu documentación solo tiene páginas de referencia, el desarrollador tiene que reconstruir el flujo de trabajo a partir de piezas sueltas.
Por eso la documentación "completa" puede sentirse inutilizable.
Empieza por las tareas que los desarrolladores realmente tienen
Para la mayoría de las APIs, la documentación real debería comenzar con rutas de tareas:
- autenticar una solicitud
- crear el primer recurso
- actualizar el recurso de forma segura
- escuchar un webhook
- reintentar una operación fallida
- pasar del modo de prueba a producción
Luego, cada tarea puede enlazar a la referencia del endpoint.
La guía comienza con el objetivo del desarrollador, muestra una ruta funcional, incluye ejemplos, luego enlaza a los detalles exactos del endpoint.
El orden importa. Si la primera página es una tabla de referencia gigante, le estás pidiendo al lector que construya el modelo mental solo.
Muestra una ruta completa, no llamadas aisladas
La documentación mala muestra una solicitud perfecta:
POST /customersLa documentación mejor muestra la secuencia:
- Crear el cliente.
- Crear la suscripción.
- Almacenar los ids devueltos.
- Escuchar el webhook de confirmación.
- Manejar los estados de falla y cancelación.
La secuencia es lo que los desarrolladores necesitan para implementar la integración.
Aún mejor, incluye la forma de la máquina de estados:
La documentación de errores es parte de la integración
Una API seria les dice a los desarrolladores qué hacer cuando las cosas fallan.
No te detengas en:
{ "error": "invalid_request" }Documenta:
- si la solicitud es segura para reintentar
- si la operación pudo haber tenido éxito parcial
- qué errores requieren acción del usuario
- qué errores requieren acción del operador
- qué id enviar al soporte
- si el webhook es la fuente autorizada
Aquí es donde la documentación de API se convierte en infraestructura de confianza.
Usa ejemplos que coincidan con la realidad de producción
El ejemplo no debería ser un juguete si el flujo de trabajo de producción no lo es.
Malo:
{ "name": "John" }Mejor:
{
"externalId": "acct_123",
"email": "operator@example.com",
"plan": "studio-audit",
"metadata": {
"source": "route-finder",
"campaign": "content-engine"
}
}El mejor ejemplo enseña nombres, metadatos, idempotencia y atribución. Ayuda al desarrollador a construir la cosa real.
Agrega una lista de verificación antes de producción
Cada API con impacto comercial real debería incluir una lista de verificación de lanzamiento.
Esta lista de verificación no reemplaza la referencia. Hace que la referencia sea utilizable.
Haz que la documentación sea comprobable
La mejor documentación de API está lo suficientemente cerca del sistema como para que pueda fallar cuando el sistema cambia.
Eso puede significar:
- ejemplos generados a partir de esquemas tipados
- ejemplos de solicitudes validados en CI
- salida de OpenAPI verificada contra los manejadores de rutas
- enlaces de documentación verificados en cada compilación
- pruebas de contrato para el flujo de trabajo público
Si la documentación se mantiene manualmente lejos del código, se desviará. Cuando se desvía, los desarrolladores dejan de confiar en ella.
La estructura que me gusta
Para una API seria, enviaría esta arquitectura de información:
- Empieza aquí: qué hace la API y qué puedes construir.
- Inicio rápido: una ruta feliz completa.
- Autenticación: claves, alcances, rotación, configuración local.
- Flujos de trabajo principales: guías basadas en tareas.
- Webhooks/eventos: entrega, reintentos, firmas, reproducción.
- Errores/reintentos: qué falló y qué hacer.
- Referencia: detalle a nivel de endpoint.
- Lista de verificación de producción: barreras de seguridad para el lanzamiento.
- Registro de cambios: cambios disruptivos y notas de migración.
Eso no es exagerado. Eso es lo que permite que alguien se integre sin un ingeniero de ventas sentado a su lado.
