No entiendo por qué no existe documentación completa para todos los puntos de la API. La documentación original se publicó al público en diciembre de 2014, y aquí estamos, seis años después, y la documentación sigue siendo incompleta.
¿Por qué es esto? La falta de una buena documentación y la sugerencia de realizar ingeniería inversa de la API representan una barrera significativa para los desarrolladores que buscan utilizar la API.
Atentamente,
Un desarrollador frustrado
¿Podrías darnos algunos ejemplos de lo que te está resultando difícil o de lo que sientes que falta?
Este es un tema de actualidad porque tengo una advertencia en mi foro: «Hemos detectado una solicitud de API que utiliza un método de autenticación obsoleto».
Me gustaría saber cuál es el método actual que debo usar y una guía paso a paso para implementarlo desde la perspectiva del administrador del foro.
Lo que he encontrado son hilos anticuados que enlazan a GitHub, y como persona no técnica, las referencias al código no me son de ayuda. ¿Alguien puede ofrecer orientación en lenguaje sencillo?
La autenticación correcta de la API se explica en la documentación, justo al principio. En resumen, debes usar encabezados HTTP para proporcionar la clave de API y el nombre de usuario en lugar de parámetros de URL.
@justin Mi ejemplo concreto es que estoy trabajando lentamente en lanzar un envoltorio en Python para la API de Discourse, y me abruma la falta de documentación adecuada. Ya tengo que probar manualmente cada uno de los endpoints, pero muchos de ellos o no están documentados o lo están de manera incorrecta.
En la parte superior de la documentación se indica claramente que la API no está completamente documentada. Quiero saber: ¿Por qué?
Vea Reverse engineer the Discourse API
¿Por qué no está “totalmente documentado” cada grano de arena en una playa? 
Por curiosidad, ¿por qué no simplemente apoyan lo que se requiere hasta que encuentran un nuevo requisito no compatible, momento en el que lo hacen ingeniería inversa? Eso es mucho más fácil que apuntar al 100% y no tiene sentido envolver llamadas que nunca se usarán. Especialmente porque estarán apoyando un objetivo en movimiento. ¿No sería más fácil para su vida?
Entiendo que esto puede ser objeto de ingeniería inversa. Solo es un poco frustrante tener que hacerlo. La API fue creada por personas que deben saber cómo funciona; ¿por qué no pueden esas personas documentarlo para que otros estén informados?
No creo que esto sea una gran petición. Una buena documentación es crucial en cualquier proyecto.
Ese es el plan por ahora; tengo todos los endpoints documentados reflejados en mi repositorio, en la rama develop, y he llegado al punto en el que tendré que empezar a hacer ingeniería inversa.
Ya estoy empezando a contribuir en GitHub - discourse/discourse_api_docs: Discourse API Documentation · GitHub, pero realmente me pregunto por qué es necesario esto en un proyecto tan consolidado.
Como en todo, se trata de recursos y prioridades. La superficie de la API es enorme. Técnicamente, lo abarca todo: todo se accede a través de la API, de ahí que funcione la ingeniería inversa. Hemos decidido centrar nuestro tiempo limitado de ingeniería en correcciones, nuevas funciones, rendimiento, etc., en lugar de en la documentación. La dirección de nuestro producto está impulsada en gran medida por nuestros clientes y nuestra comunidad. Que yo sepa, ningún cliente ha solicitado nunca una cobertura del 100 % de la documentación de la API. Cuando los clientes preguntan sobre algo que falta o no está claro, lo añadimos. Por lo tanto, la cobertura del 100 % no ha sido una prioridad.
En este momento, la documentación de la API se elabora manualmente. Obviamente, este no es un método sostenible, pero por ahora es lo que tenemos. La refactorización del sistema de documentación de la API para que se genere programáticamente es una tarea pendiente, pero actualmente no está programada para ninguna versión específica, por lo que no hay un cronograma para su finalización.