Espero esclarecer quando e para quais finalidades os dois sistemas de autenticação da API do Discourse operam.
(de aqui). Esta é a minha melhor compreensão:
A Admin API, às vezes também referida como JSON API, pode ser usada quando você deseja fazer chamadas de API para interagir com um fórum Discourse e:
- essas chamadas não exigem autenticação, ou
- essas chamadas exigem autenticação, mas você tem controle direto sobre o fórum Discourse também, de modo que pode gerar manualmente chaves de API que seu fórum e/ou o aplicativo separado podem usar para fazer as chamadas de API.
A User API, por outro lado, é destinada a quando você deseja interagir com um fórum Discourse (ou fóruns), as interações exigem autenticação e você não controla o fórum (ou fóruns) com o qual deseja interagir.
Outra forma de dizer: a Admin API é para quando você controla o fórum com o qual está interagindo, e a User API é para quando você não controla o fórum.
Isso está correto?
Por exemplo, a descrição de @david aqui diz que a Admin API não deve ser usada com clientes JavaScript. Mas acredito que seja aceitável usar a Admin API com clientes JavaScript, desde que o proprietário do aplicativo que os clientes JavaScript usam também controle o fórum (ou seja, o proprietário do aplicativo separado é o mesmo que o proprietário do fórum). Certo?
Eu acho que é assim que funciona. Se você deseja fazer chamadas à Admin API relacionadas a um site Discourse a partir de um aplicativo separado, acredito que pode fazer essas chamadas no lado do servidor (a partir de um backend). Se você não as fizer a partir de um backend — e fizer do lado do cliente —, poderá encontrar restrições de CORS. Nesse caso, você pode adicionar o domínio do aplicativo separado à lista de permissões em admin/site_settings/security/ → “cors origins”.
Abaixo, incluí também mais detalhes sobre como essas APIs funcionam. Outra pergunta que ainda tenho: ao definir uma chave de API para a Admin API, quando é apropriado usar “Todos os Usuários” como nível de usuário?
Mais Detalhes:
A Admin API
O Básico
Esta é a API descrita em docs.discourse.org. Às vezes referida como JSON API.
Ao interagir com os endpoints dessa API, você pode fazer praticamente tudo o que poderia fazer diretamente em um site Discourse, usando o método descrito aqui.
Certos endpoints exigem autenticação. Por exemplo, se você deseja usar a API para recuperar detalhes de um grupo específico (endpoint: [your-forum]/groups/[group-name].json), mas esse grupo é visível apenas para seus membros, então você precisará fazer a chamada ao endpoint “em nome de” um dos membros.
Para fazer a chamada de API usando autenticação adequada, você precisará gerar uma chave de API em [your-forum]/admin/api → New API Key, selecionando para essa chave o Nível de Usuário “Single User” e escolhendo um usuário autorizado a visualizar o recurso (como informações sobre um grupo).
Ao fazer a chamada de API, inclua os cabeçalhos: a chave como Api-Key e o nome de usuário do usuário como Api-Username.
Também há a opção, ao definir a chave de API, de escolher “Todos os Usuários”. Conforme minha pergunta acima, não tenho certeza de quando isso é apropriado versus, digamos, escolher um único usuário e ter esse usuário como administrador.
Quando Usar
Você pode usar a Admin API “dentro” do seu aplicativo Discourse. Portanto, você pode interagir com a Admin API: (i) a partir do painel Editar CSS/HTML para cada tema em [your-forum]/admin/customize, (ii) a partir de um tema que você integra ao seu site Discourse e (iii) a partir de um plugin que você integra ao seu site Discourse.
Você também pode usar a Admin API a partir de um aplicativo separado, se você controlar o fórum Discourse, de modo que possa, por meio do fórum, gerar manualmente a(s) chave(s) de API que o aplicativo separado usará.
Conforme minha pergunta acima, esta é a compreensão que espero confirmar.
A User API
Os detalhes dessa API são descritos aqui: User API keys specification
Acredito que a User API exista porque a Admin API não deve ser usada como uma API geral acessível a qualquer site ou aplicativo separado do seu fórum.
Para deixar claro: existem dois cenários diferentes em que um aplicativo separado pode interagir com seu fórum Discourse:
Cenário 1: Sem Conexão Direta: Um desenvolvedor que não está conectado ao fórum Discourse cria um aplicativo que interage com o fórum. Por exemplo, um desenvolvedor que não é administrador do fórum ou de outra forma conectado ao administrador do fórum deseja criar um aplicativo que consulte vários sites Discourse para obter alguns fatos sobre eles ou informações deles.
Nesse cenário, o administrador do fórum Discourse não vai gerar manualmente uma chave de API para entregar ao desenvolvedor desconectado. Portanto, a Admin API não é adequada.
Assim como muitos sites, como o YouTube, possuem uma API que desenvolvedores de terceiros podem usar para interagir com o YouTube nos aplicativos que criam, a User API do Discourse é uma maneira para aplicativos de terceiros interagirem com seu fórum, permitindo que os clientes (desktops, celulares) que usam os aplicativos gerem uma chave de API que lhes concede acesso limitado ao fórum.
Cenário 2: Um Aplicativo Conectado Diretamente: O administrador de um fórum (ou um desenvolvedor conectado ao administrador) está conectado a um aplicativo separado com o qual o administrador deseja que o fórum interaja.
Por exemplo, talvez um administrador queira que haja um aplicativo separado com recursos não relacionados ao Discourse, e ele/ela deseja que haja sobreposição entre os usuários do aplicativo separado e do fórum. Nesse caso, o administrador pode realmente gerar diretamente (manualmente, através do painel de administração do fórum) as chaves de API e fornecê-las ao aplicativo separado para uso, de modo que o aplicativo separado possa utilizar a Admin API.