Estoy buscando una forma de obtener una lista definitiva de los puntos de conexión de la API disponibles en mi instancia de Discourse. A veces puede ser difícil saber qué APIs están disponibles para mí cuando busco crear una integración en la plataforma.
5 Me gusta
No creo que eso sea técnicamente posible. Discourse no tiene una ruta de descubrimiento de API (por ejemplo, algo similar a la ruta /wp-json de WordPress). Lo más parecido que conozco es la documentación en https://docs.discourse.org/.
Para integraciones que no están cubiertas por la documentación, probablemente la forma más rápida de averiguar si son factibles es preguntar aquí sobre cómo lograr algún objetivo específico. La regla general con la API es que todo lo que se puede hacer a través de la interfaz de usuario de Discourse también se puede hacer a través de la API.
9 Me gusta
¡Agradezco la respuesta, Simon! Estoy familiarizado con docs.discourse.org (que, curiosamente, no son los docs oficiales sino las especificaciones de la API).
También estoy familiarizado con el uso de la consola de mi navegador para capturar solicitudes, así como con la revisión de archivos routes.rb.
Como puedes imaginar, las dos opciones anteriores son bastante tediosas y no muy amigables para el usuario. Para aquellos de nosotros que buscamos construir integraciones profundas rápidamente, especialmente si tenemos otros equipos en nuestro negocio o terceros que desean integrarse… decirles que hagan las cosas anteriores ha tenido una respuesta terriblemente pobre.
Si bien soy consciente de la flexibilidad de las capacidades de Discourse, desarrollar o integrarse con la plataforma es una batalla cuesta arriba, por decir lo menos. Como último recurso, esperaba que hubiera una forma programática de agregar las APIs públicas.
7 Me gusta
La fuente definitiva, aparte de la fuente, es Ingeniería inversa de la API de Discourse.
Todo lo que puedes hacer en el frontend lo puedes hacer con la API. Hay muy pocas cosas que solo puedes hacer con la API.
3 Me gusta
¿Puedes aclarar un poco más a qué te refieres con esto?
Si bien el punto de Simon sobre que estos no cubren las API implementadas por extensiones de Discourse (por ejemplo, plugins), esta documentación es oficial en el sentido de que la mantenemos.
Eso no quiere decir que no tengamos bastante margen de mejora en cuanto a la documentación de la API del lado del servidor y la API en sí, pero sí quería entender un poco mejor tus comentarios sobre la documentación que ya existe.
1 me gusta
¡Claro! Esto es probablemente más de lo que pediste 
Creo que aquí guardas tu documentación oficial del producto, ¿correcto?
Yo diría que el matiz es que las especificaciones de la API son un subconjunto de la documentación. Así que siempre lo olvido y me sorprende un poco cuando señalo a alguien a docs.discourse.org y olvido que ese enlace no va a la documentación de Discourse… va a un conjunto limitado de especificaciones de API.
Así que les digo una versión de:
Gracias por reunirnos hoy, me alegra que estés interesado en ver qué tipo de experiencia puedes crear para nuestros usuarios utilizando la nueva Netwrix Community.
La documentación está en https://meta.discourse.org/c/documentation/10.
docs.discourse.org no es en realidad su documentación, sino sus especificaciones de API. Sé que preguntaste sobre la integración con la nueva comunidad que estamos construyendo. Desafortunadamente, no tengo una página a la que pueda dirigirte que muestre toda la funcionalidad que ofrece Discourse, pero puedes ir a docs.discourse.org para tener una idea de solo una parte de lo que es posible.
Lo que hago en este escenario, porque no puedo darles una lista definitiva de los puntos finales existentes, es simplemente decirles: “Asume que todo lo que puedas concebir es posible. Yo investigaré lo que Discourse puede hacer y lo reduciremos a partir de ahí si es necesario”.
Pero sería genial si todas las API estuvieran listadas en las especificaciones, ¿eh?
Más contexto…
Sería raro si comprara un coche y me dieran una hoja de características y yo preguntara: “¿Genial! ¿Eso es todo entonces?”
“Bueno, no… pero si solo miras debajo del capó y sigues el cableado de 12v y las abrazaderas de manguera alrededor del motor, deberías poder ver a qué se conectan y hacer ingeniería inversa de lo que más hace”.
Claro, el mecánico/desarrollador/persona con mentalidad técnica en este escenario puede hacer eso. Pero no todo el mundo 
Además, incluso como desarrollador, no quiero:
- Aprender Ruby para ver dónde podrían existir rutas
- Hacer ingeniería inversa de todos los archivos routes.rb para tener una idea de los puntos finales disponibles
- Refinar aún más esa ingeniería inversa para averiguar qué entradas requieren, cuál es la estructura de objetos de la salida
- Buscar qué plugins tengo también
- Repetir en sus archivos routes.rb (¿creo? No sé Ruby, así que no estoy seguro)
- …y 6 meses después, entre mi trabajo diario y esto, tengo una respuesta.
Digo todo esto con cariño: no hay hoy en día ninguna plataforma que se compare con las capacidades de la plataforma Discourse. Punto. Es el producto más sólido, potente, flexible y rentable del mercado y está a años luz de la competencia.
Sus deficiencias no son su robustez, potencia y flexibilidad. De hecho, esas son algunas de las mayores ventajas de Discourse que los productos de la competencia tendrán dificultades o incluso fallarán en emular.
- No es que sus API no sean geniales, es que encontrarlas es difícil.
- No son los paneles de administración con muchas opciones los que dificultan la adopción, sino la falta de educación y nombres de configuraciones de administración como
Solo la primera publicaciónque son, en el mejor de los casos, ambiguos. - No es su implementación robusta pero simple (¡y perfectamente así!) de una estructura de herramientas comunitarias de categorías, temas y etiquetas, sino que la información no existe para educar e inspirar a los usuarios de que no tiene que ser una categoría, sino un blog, o un tablón de anuncios de productos, o un portal de ideas… y no tienen que ser temas, sino que pueden ser blogs, anuncios de productos e ideas.
Esto es lo único que le falta a Discourse como producto para mí: el pulido, los detalles finales.
9/10, lo compraría de nuevo.
7 Me gusta
De acuerdo, creo que entiendo mejor, gracias.
Lo que sigue son mis propias opiniones; no las he consultado con personas más expertas que yo, así que es posible que me corrijan en algunas cosas que estoy diciendo mal aquí.
Nuestra documentación de historias también está evolucionando. Hemos logrado avances significativos, pero aún queda un largo camino por recorrer. Permítanme intentar recapitular un poco.
Primero, como una especie de modelo mental de nivel superior, describiría las cosas de esta manera:
- Nuestro punto de entrada principal para la documentación está aquí, como usted señaló: Documentation - Discourse Meta
- Para la documentación para desarrolladores, está aquí, o quizás mejor aún, aquí: Introduction to Discourse Development
- La documentación de la API es un subconjunto de la documentación para desarrolladores y se encuentra aquí: https://docs.discourse.org/
- Para la documentación para desarrolladores, está aquí, o quizás mejor aún, aquí: Introduction to Discourse Development
Yo llamaría a la documentación de la API documentación en lugar de especificaciones, pero estoy de acuerdo en que sigue siendo un subconjunto de nuestra documentación para desarrolladores. La URL de esa documentación es extraña… tendría más sentido que nuestra documentación completa viviera allí o que fuera una redirección a https://meta.discourse.org/c/documentation/10, y que hubiera una señal clara desde Introduction to Discourse Development hacia la documentación de la API.
Nuestra documentación para desarrolladores está en proceso de mejora. El historial de confirmaciones aquí probablemente cuenta la mejor historia sobre dónde ha ido el esfuerzo hasta ahora: Commits · discourse/discourse-developer-docs · GitHub
La documentación de la API podría describirse como incompleta, pero tenemos trabajo que hacer para aclarar nuestra historia aquí. En el pasado, solíamos señalar “ingeniería inversa de la API”, pero estoy de acuerdo en que no es una buena historia. Está bien para hackear bajo su propio riesgo, pero puede haber casos en los que los puntos finales que no figuran allí es mejor no depender de ellos.
La API del lado del servidor está destinada principalmente a ser consumida por nuestra aplicación frontend. En el frontend, proporcionamos una API de JavaScript que sería una mejor interfaz para consumir, ya que puede ocultar los cambios realizados en el backend: Using the JS API
Entonces, ¿qué garantías de estabilidad podemos hacer sobre nuestra API de backend?
Creo que esa es una responsabilidad que la documentación de la API debería abordar. Idealmente, lo que se documenta allí es un subconjunto de todos los puntos finales que admitimos, pero un subconjunto intencional que pretendemos admitir para otros que crean integraciones, mientras que las cosas que no figuran allí son intencionalmente no documentadas como cosas que solo están destinadas a nuestro frontend, que pueden cambiar sin previo aviso.
Idealmente (en mi opinión), tendríamos la documentación integrada en el código fuente de una manera que la documentación en sí misma esté bajo prueba, sea extensible con complementos, sea servida por la propia aplicación para que esté sincronizada con la instancia que se está documentando; de esa manera, podría ver la documentación de la API para un sitio determinado y ver la documentación de la versión que se está ejecutando, con los complementos que realmente están instalados y habilitados.
Sé que otras personas internamente han tenido muchas discusiones sobre otras ideas para mejorar nuestra historia de la API del lado del servidor.
Aún no hemos podido priorizar mucho en este espacio, ya que nuestro enfoque principal en cuanto a la experiencia del desarrollador en los últimos dos años ha sido la modernización de nuestro frontend.
No estoy seguro de cuándo es probable que eso cambie, pero estaremos atentos a las cosas más pequeñas que podamos hacer en el camino para seguir avanzando en la historia de la API del lado del servidor. Si surgen preguntas específicas, quizás podamos usarlas como impulso para realizar mejoras más específicas mientras tanto.
5 Me gusta
Las garantías de estabilidad deben abordarse mediante un control de versiones de API sencillo.
Este tema no trata de dónde vive la documentación, sino de cómo se documenta la API. Lo que falta es un formato estandarizado y legible por máquina como OpenAPI.
Esa ausencia, junto con la falta de control de versiones, hace que el trabajo de integración sea más difícil y frágil de lo que debería ser. Incluso un esquema OpenAPI básico para los puntos finales documentados sería de gran ayuda.
3 Me gusta
Fundamentalmente, este no es un problema de documentación, es un problema de implementación.
@avdi planteó esto hace años y existe un amplio consenso interno de que el camino correcto a seguir es una API REST/JSON versionada adecuada con parámetros y formas de datos consistentes.
Actualmente, la API que enviamos es nuestra API interna. Está 100% completa y es exhaustiva, pero es torpe y cambia de forma. Las formas que devuelve y los puntos finales están optimizados para impulsar la aplicación Ember del lado del cliente. Evoluciona y cambia de forma a medida que pasan los meses, lo que dificulta depender de ella para tareas de misión crítica. Construir sobre ella es más complejo de lo necesario.
Un conjunto completamente nuevo de controladores y rutas resolvería el problema de estabilidad aquí y nos permitiría devolver formas que tengan más sentido para una API REST. Por ejemplo:
/api/v0/topic/1234.json podría devolver una forma mucho más “consistente con la práctica general de API”.
Hay demasiadas “preocupaciones exclusivas del cliente Ember” muy complicadas en nuestro JSON de temas:
timeline_lookup, post_stream, tags_descriptions, etc., etc.
Dicho esto, este es un proyecto masivo para emprender, necesitaríamos una gran cantidad de rediseño interno para asegurarnos de no duplicar la lógica. Además, los complementos complican esto aún más porque remodelan gran parte del comportamiento interno que debería reflejarse en la API. (¿qué hace assign a estas formas?)
Ciertamente veo que nos embarcamos en esta aventura, pero no en un futuro cercano.
10 Me gusta
Creo que es completamente razonable que el cambio lleve tiempo. Dirigí las Relaciones con Desarrolladores en mi última empresa y, por Dios… tardamos más de dos años en mejorar nuestras API. Había tantas cosas complejas a considerar (¡y a ingeniería le odiaba la idea de crear un punto final estable que no pudiera cambiar!).
Sin embargo, creo que los cambios más pequeños también pueden ocurrir con el tiempo y en un plazo más corto. Admito que no he investigado cómo se definen sus rutas (o cómo se definen las rutas en Ruby), pero supongo que algunas mejoras fáciles podrían abordarse con bastante facilidad. Por ejemplo:
No puedo hablar por todos, pero siento que incluso tener los puntos finales en su especificación de API actual, aunque no tuvieran descripciones y ejemplos, y aunque el modelo de respuesta fuera fluido, sería una gran victoria. A veces, simplemente saber que algo existe es la mitad de la batalla.
5 Me gusta
¿La documentación de la API está en formato OpenAPI?
https://docs.discourse.org/openapi.json
{
"openapi": "3.1.0",
"info": {
"title": "Documentación de la API de Discourse",
"x-logo": {
"url": "https://docs.discourse.org/logo.svg"
},
"version": "latest",
...
6 Me gusta
Debo admitir vergonzosamente que nunca me había dado cuenta de eso…
Gracias @blake por señalar esto.
2 Me gusta