Escribiré documentación clara de API que sus desarrolladores podrán seguir desde el primer día

Por qué la mayoría de las documentaciones de API fallan

Describen los puntos finales y omiten las partes que realmente detienen a las personas: cómo autenticarse, cómo se ve una solicitud realista, qué significa el error y qué hacer al respecto. El lector luego abre un ticket de soporte, que es el costo que la documentación existe para eliminar.

Cómo lo escribo

Desde la fuente, no de memoria. Leo las rutas, la capa de validación y los manejadores de errores, luego llamo a la API yo mismo con credenciales reales. Cada ejemplo en la documentación es una solicitud que hice y una respuesta que recibí, sin cargas útiles inventadas, sin códigos de estado que el punto final nunca devuelve.

Qué contiene la documentación

• Autenticación: obtención de un token, su actualización y qué sucede cuando expira a mitad de sesión.
• Cada punto final con parámetros, una solicitud de ejemplo completa y la forma de respuesta real.
• Una referencia de errores que mapea cada código de error a una causa y una solución, en lugar de simplemente repetir el mensaje.
• Una ruta de inicio que lleva a un nuevo desarrollador de cero a una llamada exitosa en menos de diez minutos.
• Límites de velocidad, paginación, webhooks e idempotencia explicados donde realmente se aplican.

Formato

Markdown en su repositorio, estructurado para OpenAPI o un sitio de documentación, lo que sea que realmente mantendrá. Ejemplos de código en los lenguajes sobre los que preguntan sus usuarios, verificados ejecutándolos. Colección de Postman o similar incluida si desea una.

Lo que necesito

Acceso al repositorio o al archivo OpenAPI, una credencial de trabajo para un entorno de prueba y cualquier pregunta que su equipo de soporte esté cansado de responder. Esas preguntas son el esquema.

No incluido

Texto de marketing. Esto documenta lo que hace el software, precisamente; la página de destino es un arte diferente.

Tiempo de respuesta y comunicación

Un primer borrador completo suele llegar en una semana, y usted lo revisa con las preguntas que su propio equipo de soporte sigue respondiendo. Prefiero que me corrija temprano el ingeniero que conoce los casos extremos que entregar algo pulido y equivocado. Cada ejemplo en el documento final ha sido ejecutado contra su API, por lo que nada en él es aspiracional.