Espero aclarar cuándo y con qué fines operan los dos sistemas de autenticación de la API de Discourse.
(de aquí). Esta es mi mejor comprensión:
La API de Administración, a veces también denominada API JSON, puede utilizarse cuando deseas realizar llamadas a la API para interactuar con un foro de Discourse y:
- esas llamadas no requieren autenticación, o
- esas llamadas sí requieren autenticación, pero tienes control directo sobre el foro de Discourse, por lo que puedes generar manualmente claves de API que tu foro y/o la aplicación separada puedan usar para realizar las llamadas a la API.
La API de Usuario, por otro lado, está pensada para cuando deseas interactuar con un foro de Discourse (o foros), las interacciones requieren autenticación y no tienes control sobre el foro (o foros) con los que quieres interactuar.
Otra forma de decirlo: la API de Administración es para cuando controlas el foro con el que estás interactuando, y la API de Usuario es para cuando no controlas el foro.
¿Es esto correcto?
Por ejemplo, la descripción de @david aquí indica que la API de Administración no está pensada para usarse con clientes de JavaScript. Pero creo que está bien usar la API de Administración con clientes de JavaScript siempre que el propietario de la aplicación que utilizan los clientes de JavaScript también controle el foro. (es decir, el propietario de la aplicación separada es el mismo que el del foro). ¿Verdad?
Pienso que así es como funciona. Si deseas realizar llamadas a la API de Administración sobre un sitio de Discourse desde una aplicación separada, creo que puedes hacer esas llamadas en el lado del servidor (desde un backend). Si no las realizas desde un backend y las haces desde el lado del cliente, podrías encontrarte con restricciones de CORS. En ese caso, puedes añadir a la lista blanca el dominio de la aplicación separada en admin/site_settings/security/ → “cors origins”.
A continuación, también incluyo más detalles sobre cómo funcionan estas APIs. Otra pregunta que aún tengo: cuando estás configurando una clave de API para la API de Administración, ¿cuándo es apropiado usar “Todos los usuarios” como nivel de usuario?
Más detalles:
La API de Administración
Lo básico
Esta es la API descrita en docs.discourse.org. A veces se le llama API JSON.
Al interactuar con los puntos finales (endpoints) de esta API, puedes hacer prácticamente cualquier cosa que podrías hacer directamente en un sitio de Discourse, utilizando el método descrito aquí.
Ciertos puntos finales requieren autenticación. Por ejemplo, si deseas usar la API para obtener detalles de un grupo en particular (punto final: [tu-foro]/grupos/[nombre-del-grupo].json), pero ese grupo solo es visible para sus miembros, entonces deberás realizar la llamada al punto final “en nombre de” uno de los miembros.
Para realizar la llamada a la API con la autenticación adecuada, necesitarás generar una clave de API en [tu-foro]/admin/api → Nueva clave de API, seleccionando para esa clave el nivel de usuario “Usuario único” y eligiendo un usuario autorizado para ver el recurso (como información sobre un grupo).
Cuando realices la llamada a la API, incluirás las cabeceras: la clave como Api-Key y el nombre de usuario del usuario como Api-Username.
También existe la opción, al configurar la clave de API, de elegir “Todos los usuarios”. Según mi pregunta anterior, no estoy seguro de cuándo es apropiado esto en comparación con, por ejemplo, elegir un solo usuario y que ese usuario sea el administrador.
Cuándo usarla
Puedes usar la API de Administración “desde dentro” de tu aplicación de Discourse. Así que puedes interactuar con la API de Administración: (i) desde el panel de edición de CSS/HTML para cada tema bajo [tu-foro]/admin/customize, (ii) desde un tema que integres en tu sitio de Discourse, y (iii) desde un plugin que integres en tu sitio de Discourse.
También puedes usar la API de Administración desde una aplicación separada, si controlas el foro de Discourse de modo que puedas, a través del foro, generar manualmente la(s) clave(s) de API que la aplicación separada utilizará.
Según mi pregunta anterior, esta es la comprensión que espero confirmar.
La API de Usuario
Los detalles de esta API se describen aquí: User API keys specification
Creo que la API de Usuario existe porque la API de Administración no está pensada para usarse como una API general accesible para cualquier sitio o aplicación separado de tu foro.
Para ser claros al respecto: hay dos escenarios diferentes en los que una aplicación separada podría interactuar con tu foro de Discourse:
Escenario 1: Sin conexión directa: Un desarrollador que no está conectado al foro de Discourse crea una aplicación que interactúa con el foro. Por ejemplo, un desarrollador que no es administrador del foro ni está conectado de otra manera con el administrador del foro quiere crear una aplicación que consulte varios sitios de Discourse para obtener algunos datos o información sobre ellos.
En este escenario, el administrador del foro de Discourse no generará manualmente una clave de API para dársela al desarrollador no conectado. Por lo tanto, la API de Administración no es apropiada.
Así como muchos sitios como YouTube tienen una API que los desarrolladores de terceros pueden usar para interactuar con YouTube en las aplicaciones que crean, la API de Usuario de Discourse es una forma de que las aplicaciones de terceros interactúen con tu foro permitiendo que los clientes (escritorios, teléfonos móviles) que usan las aplicaciones generen una clave de API que les otorgue acceso limitado al foro.
Escenario 2: Una aplicación directamente conectada: El administrador de un foro (o un desarrollador conectado al administrador) está conectado a una aplicación separada con la que el administrador quiere que el foro interactúe.
Por ejemplo, quizás un administrador quiere que exista una aplicación separada con funciones que no son de Discourse, y desea que haya una superposición entre los usuarios de la aplicación separada y los del foro. En este caso, el administrador puede generar directamente (manualmente a través del panel de administración del foro) las claves de API y proporcionarlas a la aplicación separada para que las utilice, de modo que la aplicación separada pueda usar la API de Administración.