Я ищу способ получить полный список доступных в моем экземпляре Discourse API-эндпоинтов. Иногда бывает сложно понять, какие API доступны для создания интеграции с платформой.
Полагаю, что технически это невозможно. У Discourse нет маршрута для обнаружения API (например, аналогичного маршруту /wp-json в WordPress). Ближайший к этому вариант, о котором мне известно, — это документация по адресу https://docs.discourse.org/.
Для интеграций, не охваченных документацией, скорее всего, самый быстрый способ понять, реализуемы ли они, — спросить здесь, как достичь конкретной цели. Общее правило для API таково: всё, что можно сделать через интерфейс Discourse, также можно сделать через API.
Спасибо за ответ, Саймон! Я знаком с docs.discourse.org (что, как ни странно, не является официальной документацией, а скорее спецификациями API).
Также я привык использовать консоль браузера для перехвата запросов, а также изучать файлы routes.rb.
Однако, как вы можете себе представить, оба этих варианта довольно утомительны и не совсем удобны для пользователя. Для тех из нас, кто стремится быстро создать глубокие интеграции, особенно если в нашем бизнесе есть другие команды или сторонние поставщики, желающие подключиться, предложение им сделать вышеперечисленное вызывало крайне негативную реакцию.
Хотя я осознаю гибкость возможностей Discourse, разработка на платформе или интеграция с ней — это, мягко говоря, тяжёлая борьба. В отчаянной попытке я надеялся, что существует программный способ агрегации публичных API.
Достоверный источник, помимо самого источника, — это реверс-инжиниринг API Discourse.
Всё, что можно сделать на фронтенде, можно сделать и через API. Существует очень немного функций, доступных только через API.
Не могли бы вы немного подробнее пояснить, что вы имеете в виду?
Хотя Саймон верно заметил, что эти материалы не охватывают API, реализованные в расширениях для Discourse (например, в плагинах), эти документы являются официальными в том смысле, что мы их поддерживаем.
Это не значит, что у нас нет значительного пространства для улучшений в документации серверного API и в самом API, но я действительно хотел бы лучше понять вашу обратную связь по поводу существующей документации.
Конечно! Это, вероятно, больше, чем вы просили 
Я полагаю, что ваша официальная документация по продукту находится здесь, верно?
На мой взгляд, нюанс заключается в том, что спецификации API являются подмножеством документации. Поэтому я всегда забываю об этом, и меня это застает врасплох на секунду, когда я направляю кого-то на docs.discourse.org и вдруг вспоминаю, что эта ссылка ведет не на документацию Discourse… а на ограниченный набор спецификаций API.
Поэтому я говорю им примерно следующее:
Спасибо, что встретились сегодня. Я рад, что вы заинтересовались тем, какой опыт вы можете создать для наших пользователей, используя новое сообщество Netwrix!
Документация на самом деле находится здесь: https://meta.discourse.org/c/documentation/10.
docs.discourse.org — это не их документация, а их спецификации API. Я знаю, что вы спрашивали о интеграции с новым сообществом, которое мы создаем. К сожалению, у меня нет страницы, на которую я мог бы вас направить, где показаны все функции, предлагаемые Discourse, но вы можете перейти на docs.discourse.org, чтобы получить представление о некоторых возможностях.
В такой ситуации, поскольку я не могу предоставить им исчерпывающий список существующих конечных точек (endpoints), я просто говорю: «Предположите, что возможно всё, что вы только можете себе представить. Я пойду и узнаю, что может сделать Discourse, и если потребуется, мы сузим этот список».
Но было бы здорово, если бы все API были перечислены в спецификациях, не так ли?
Дополнительный контекст…
Было бы странно, если бы я купил машину, а мне дали список функций, и я спросил: «Круто! Это всё, что есть?»
«Ну, нет… но если вы просто заглянете под капот, проследите некоторые 12-вольтовые провода и хомуты вокруг двигателя, то сможете увидеть, к чему они подключены, и методом обратного инжиниринга понять, что ещё она делает».
Конечно, механики, разработчики и технически подкованные люди в такой ситуации могут это сделать. Но не все 
Кроме того, даже как разработчик, я не хочу:
- Изучать Ruby, чтобы понять, где могут существовать маршруты;
- Методом обратного инжиниринга анализировать все файлы routes.rb, чтобы получить представление о доступных конечных точках;
- Дорабатывать этот обратный инжиниринг, чтобы выяснить, какие входные данные они требуют, какова структура выходных объектов;
- Проверять, какие плагины у меня установлены;
- Повторять всё это для их файлов routes.rb (я думаю? Я не знаю Ruby, поэтому точно не уверен);
- …и через 6 месяцев, между основной работой и этим, получить ответ.
Я говорю всё это с любовью — на сегодняшний день не существует платформы, которая могла бы сравниться с возможностями платформы Discourse. Точка. Это самый сильный, мощный, гибкий и экономически эффективный продукт на рынке, превосходящий конкурентов на много голов.
Её недостатки не в надёжности, мощности и гибкости. На самом деле, именно это является одним из главных преимуществ Discourse, с которым конкурентным продуктам будет трудно, а то и невозможно, конкурировать.
- Дело не в том, что её API плохи — дело в том, что их сложно найти.
- Сложность внедрения создают не панели администратора с множеством опций, а отсутствие обучения и названия настроек администратора, такие как
Только первый пост, которые в лучшем случае двусмысленны. - Дело не в том, что её прочная, но простая (и идеально подходящая!) реализация структуры инструментов сообщества (категории, темы и теги) вызывает проблемы, а в том, что отсутствует информация, которая могла бы обучить и вдохновить пользователей: категория не обязательно должна быть категорией, это может быть блог, доска объявлений о продуктах или портал идей… а темы не обязательно должны быть темами, они могут быть блогами, объявлениями о продуктах и идеями.
Это единственное, чего, на мой взгляд, не хватает продукту Discourse: полировки — завершающих штрихов.
9 из 10, купил бы снова.
Хорошо, я думаю, теперь понимаю лучше, спасибо.
Далее излагаются мои собственные мнения — я не согласовывал их с людьми, более компетентными в этом вопросе, поэтому могу ошибаться в некоторых моментах, которые здесь излагаю неверно.
Наша документация по истории проекта также развивается. Мы достигли значительных успехов, но впереди ещё долгий путь. Позвольте мне попытаться кратко подытожить.
Во-первых, как некую высокоуровневую ментальную модель, я бы описал ситуацию так:
- Нашим основным входным пунктом для документации, как вы и указали, является эта страница: Documentation - Discourse Meta
- Документация для разработчиков находится здесь, или, возможно, ещё лучше — здесь: Introduction to Discourse Development
- Документация по API является подмножеством документации для разработчиков и расположена здесь: https://docs.discourse.org/
- Документация для разработчиков находится здесь, или, возможно, ещё лучше — здесь: Introduction to Discourse Development
Я бы назвал документацию по API именно документацией, а не спецификациями, но согласен, что она всё ещё является частью нашей документации для разработчиков. URL-адрес этой документации кажется странным… было бы логичнее, если бы вся наша документация размещалась там, или если бы этот адрес был перенаправлением на https://meta.discourse.org/c/documentation/10, а с Introduction to Discourse Development была бы чёткая ссылка на документацию по API.
Сама документация для разработчиков также проходит улучшения. История коммитов здесь, вероятно, лучше всего рассказывает о том, куда направлялись усилия до сих пор: Commits · discourse/discourse-developer-docs · GitHub
Документацию по API можно назвать неполной, но нам предстоит проделать работу, чтобы привести наше описание в соответствие с реальностью. Раньше мы рекомендовали «реверс-инжиниринг API», но я согласен, что это не лучший подход. Это допустимо для экспериментов на ваш страх и риск, однако могут быть случаи, когда конечные точки, не перечисленные там, вероятно, лучше не использовать в качестве зависимостей.
Серверный API предназначен в первую очередь для потребления нашим фронтенд-приложением. На стороне фронтенда мы предоставляем JavaScript-API, которое является лучшим интерфейсом для использования, так как оно может скрывать изменения, вносимые в бэкенд: Using the JS API
Так какие гарантии стабильности мы можем давать в отношении нашего бэкенд-API?
Я считаю, что это ответственность, которую должна решать эта документация по API. В идеале то, что там задокументировано, является подмножеством всех поддерживаемых нами конечных точек, но это намеренное подмножество, которое мы планируем поддерживать для тех, кто создаёт интеграции, тогда как то, что там не перечислено, намеренно не задокументировано как то, что предназначено только для нашего фронтенда и может меняться без предупреждения.
В идеале (на мой взгляд) документация должна быть встроена в исходный код таким образом, чтобы сама документация проходила тестирование, расширялась с помощью плагинов и обслуживалась самим приложением, чтобы она была синхронизирована с экземпляром, для которого она создается. Тогда вы могли бы просматривать документацию по API для конкретного сайта и видеть документацию для той версии, на которой он работает, с любыми установленными и включёнными плагинами.
Я знаю, что внутри компании у других коллег уже было множество обсуждений по поводу других идей по улучшению нашей истории серверного API.
Пока мы не смогли выделить приоритеты в этой области, так как наш основной фокус в вопросах опыта разработчика за последние пару лет был направлен на модернизацию нашего фронтенда.
Не знаю, когда это, скорее всего, изменится, но мы будем присматриваться к небольшим вещам, которые можно делать по пути, чтобы постепенно продвигаться вперёд в истории серверного API. Если возникнут конкретные вопросы, возможно, мы сможем использовать их как стимул для внесения более целенаправленных улучшений в промежуточное время.
Гарантии стабильности должны обеспечиваться простым версионированием API.
Эта тема не о том, где находится документация, а о том, как документирован API. Не хватает стандартизированного, машиночитаемого формата, такого как OpenAPI.
Отсутствие такого формата, наряду с отсутствием версионирования, делает работу по интеграции более сложной и хрупкой, чем это должно быть. Даже базовая схема OpenAPI для документированных конечных точек была бы очень полезна.
По своей сути это не проблема документации, а проблема реализации.
@avdi поднимал этот вопрос ещё несколько лет назад, и внутри компании сложился широкий консенсус относительно того, что правильный путь вперёд — это создание полноценного версионированного JSON/REST API с согласованными параметрами и структурами данных.
В настоящее время мы предоставляем наше внутреннее API. Оно на 100% полно и исчерпывающе, но неудобно и постоянно меняет свою форму. Возвращаемые им структуры и конечные точки оптимизированы для работы клиентского приложения на Ember. Со временем они меняются и трансформируются, что затрудняет их использование для выполнения критически важных задач. Разработка на его основе оказывается сложнее, чем необходимо.
Создание совершенно нового набора контроллеров и маршрутов решило бы проблему стабильности и позволило бы возвращать структуры, более логичные для REST API. Например:
/api/v0/topic/1234.json мог бы возвращать структуру, гораздо более «согласованную с общепринятой практикой работы с API».
В нашем JSON для тем содержится слишком много очень сложных деталей, относящихся исключительно к клиенту Ember:
timeline_lookup, post_stream, tags_descriptions и так далее…
Тем не менее, это масштабный проект, за который нам предстоит взяться. Нам потребуется значительная внутренняя переработка, чтобы избежать дублирования логики. Кроме того, плагины усложняют задачу, поскольку они меняют множество внутренних механизмов, которые должны быть отражены в API. (Как функция assign влияет на эти структуры?)
Я уверен, что мы в конечном итоге займёмся этим, но не в ближайшем будущем.
Я считаю, что совершенно нормально, что изменения потребуют времени. В моей предыдущей компании я руководил отделом разработчиков, и, боже мой… нам потребовалось более двух лет, чтобы довести наши API до улучшенного состояния. Столько сложных моментов нужно было учесть (и инженеры ненавидели саму идею создания стабильной конечной точки, которую нельзя было бы изменять!).
Однако я считаю, что более мелкие изменения могут происходить постепенно и в более короткие сроки. Признаюсь, я не изучал, как определяются ваши маршруты (или как маршруты определяются в Ruby), но предполагаю, что некоторые очевидные улучшения можно реализовать довольно легко. Например:
Я не могу говорить от имени всех, но мне кажется, что даже простое наличие конечных точек в вашей текущей спецификации API — даже без описаний и примеров, и даже если модель ответа будет изменчивой — стало бы огромным успехом. Иногда сам факт того, что что-то существует, — это уже половина дела.
Документация по API выполнена в формате OpenAPI?
https://docs.discourse.org/openapi.json
{
"openapi": "3.1.0",
"info": {
"title": "Документация API Discourse",
"x-logo": {
"url": "https://docs.discourse.org/logo.svg"
},
"version": "latest",
...
Мне стыдно признаться, что я никогда не замечал этого…
Спасибо @blake за то, что обратили на это внимание.