Я надеюсь прояснить, когда и для каких целей работают две системы аутентификации API Discourse.
(из этого источника). Вот моё наилучшее понимание:
Административный API, иногда также называемый JSON API, можно использовать, когда вы хотите делать вызовы API для взаимодействия с форумом Discourse и:
- эти вызовы не требуют никакой аутентификации, или
- эти вызовы требуют аутентификации, но у вас есть прямой контроль над форумом Discourse, поэтому вы можете вручную сгенерировать ключи API, которые ваш форум и/или отдельное приложение могут использовать для выполнения вызовов API.
Пользовательский API, с другой стороны, предназначен для случаев, когда вы хотите взаимодействовать с форумом (или форумами) Discourse, эти взаимодействия требуют аутентификации, и вы не контролируете форум (или форумы), с которыми хотите взаимодействовать.
Другими словами: Административный API используется, когда вы контролируете форум, с которым взаимодействуете, а Пользовательский API — когда вы не контролируете форум.
Это верно?
Например, в описании @david здесь говорится, что Административный API не предназначен для использования с JavaScript-клиентами. Однако я считаю, что использовать Административный API с JavaScript-клиентами допустимо, если владелец приложения, которое используют эти клиенты, также контролирует форум (то есть владелец отдельного приложения совпадает с владельцем форума). Верно?
Я думаю, что всё работает именно так. Если вы хотите делать вызовы Административного API в отношении сайта Discourse из отдельного приложения, то, по моему мнению, вы можете выполнять эти вызовы на стороне сервера (из бэкенда). Если вы не делаете их из бэкенда, а выполняете на стороне клиента, вы можете столкнуться с ограничениями CORS. В таком случае вы можете добавить домен отдельного приложения в белый список в разделе admin/site_settings/security/ → “cors origins”.
Ниже я также привёл более подробную информацию о том, как работают эти API. У меня остался ещё один вопрос: когда вы настраиваете ключ API для Административного API, когда уместно использовать уровень доступа «Все пользователи»?
Дополнительные детали:
Административный API
Основы
Это API, описанное на docs.discourse.org. Иногда его называют JSON API.
Взаимодействуя с конечными точками этого API, вы можете делать практически всё, что можно сделать напрямую на сайте Discourse, используя метод, описанный здесь.
Некоторые конечные точки требуют аутентификации. Например, если вы хотите использовать API для получения деталей конкретной группы (конечная точка: [ваш-форум]/groups/[имя-группы].json), но эта группа видна только её участникам, то вам нужно выполнить вызов к конечной точке «от имени» одного из участников.
Чтобы выполнить вызов API с правильной аутентификацией, вам нужно сгенерировать ключ API на странице [ваш-форум]/admin/api → Новый ключ API, выбрав для этого ключа уровень доступа «Один пользователь» и указав пользователя, авторизованного для просмотра ресурса (например, информации о группе).
Затем при выполнении вызова API вы добавляете заголовки: ключ как Api-Key, а имя пользователя — как Api-Username.
Также есть возможность при создании ключа API выбрать уровень доступа «Все пользователи». В связи с моим вопросом выше я не уверен, когда это уместно, в отличие от выбора одного пользователя, например, администратора.
Когда использовать
Вы можете использовать Административный API «внутри» вашего приложения Discourse. То есть вы можете взаимодействовать с Административным API: (i) из панели редактирования CSS/HTML для каждой темы в разделе [ваш-форум]/admin/customize, (ii) из темы, интегрированной в ваш сайт Discourse, и (iii) из плагина, интегрированного в ваш сайт Discourse.
Вы также можете использовать Административный API из отдельного приложения, если вы контролируете форум Discourse и можете вручную сгенерировать ключи API, которые будет использовать это отдельное приложение.
В связи с моим вопросом выше я надеюсь подтвердить именно это понимание.
Пользовательский API
Подробности этого API описаны здесь: User API keys specification
Я считаю, что Пользовательский API существует, потому что Административный API не предназначен для использования в качестве общего API, доступного любому сайту или приложению, отдельному от вашего форума.
Чтобы прояснить это: есть два разных сценария, в которых отдельное приложение может взаимодействовать с вашим форумом Discourse:
Сценарий 1: Прямой связи нет: Разработчик, не связанный с форумом Discourse, создаёт приложение, которое взаимодействует с форумом. Например, разработчик, который не является администратором форума или не связан с администратором форума, хочет создать приложение, которое опрашивает различные сайты Discourse, чтобы получить о них какие-то факты или информацию.
В этом сценарии администратор форума Discourse не будет вручную генерировать ключ API для передачи несвязанному разработчику. Поэтому Административный API не подходит.
Таким образом, точно так же, как многие сайты, такие как YouTube, имеют API, которое сторонние разработчики могут использовать для взаимодействия с YouTube в создаваемых ими приложениях, Пользовательский API Discourse позволяет сторонним приложениям взаимодействовать с вашим форумом, когда клиенты (настольные компьютеры, мобильные телефоны), использующие эти приложения, генерируют ключ API, предоставляющий им ограниченный доступ к форуму.
Сценарий 2: Приложение с прямой связью: Администратор форума (или разработчик, связанный с администратором) подключён к отдельному приложению, которое администратор хочет использовать для взаимодействия с форумом.
Например, администратор может захотеть, чтобы существовало отдельное приложение с функциями, не относящимися к Discourse, и при этом хотел бы иметь пересечение между пользователями этого отдельного приложения и форума. В этом случае администратор может напрямую (вручную через панель администратора форума) сгенерировать ключи API и предоставить их отдельному приложению для использования, чтобы это приложение могло использовать Административный API.