Discourse インスタンスで利用可能な API エンドポイントの確定リストを取得する方法を探しています。プラットフォームへの統合を構築する際に、どの API が利用可能であるかを知ることは、時に困難な場合があります。
「いいね！」 5
技術的には不可能だと思います。Discourse には API ディスカバリー ルート (たとえば、WordPress の /wp-json ルートに似たもの) がありません。私が知っている最も近いものは、https://docs.discourse.org/ にあるドキュメントです。
ドキュメントでカバーされていない統合については、特定の目標を達成する方法をここで尋ねるのがおそらく最も早い方法でしょう。API に関する一般的なルールは、Discourse UI を通じて実行できることはすべて API を通じて実行できるということです。
「いいね！」 9
サイモン、ご返信ありがとうございます！docs.discourse.org（面白いことに、これは公式ドキュメントではなくAPI仕様です）については承知しております。
ブラウザのコンソールを使用してリクエストをキャプチャしたり、routes.rbファイルを調べたりすることもできます。
ご想像のとおり、上記の両方の方法は非常に手間がかかり、ユーザーフレンドリーではありません。特に、ビジネス内の他のチームやサードパーティベンダーが統合したい場合など、迅速に深い統合を構築したい私たちにとって、上記の方法を伝えることは非常に悪い結果をもたらしました。
Discourseの機能の柔軟性については認識していますが、プラットフォームの開発または統合は、控えめに言っても困難な道のりです。最後の手段として、公開APIをプログラムで集約する方法があることを期待していました。
「いいね！」 7
ソース以外の決定的な情報源は、Discourse APIのリバースエンジニアリングです。
フロントエンドでできることはすべてAPIでも可能です。APIでしかできないことはごくわずかです。
「いいね！」 3
これをもう少し詳しく説明していただけますか？
Simon氏が指摘したように、これらはDiscourseの拡張機能（プラグインなど）によって実装されたAPIをカバーしていませんが、これらは私たちが保守しているという意味で公式です。
サーバーサイドAPIドキュメントやAPI自体に関して改善の余地がかなりあることは否定しませんが、既存のドキュメントに関するフィードバックをもう少し理解したいと思いました。
「いいね！」 1
もちろんです！おそらくご要望以上のものになるかと思います 
公式の製品ドキュメントはここに保管されていますよね？
API 仕様 は ドキュメント のサブセットであると言えます。そのため、私はいつも忘れてしまい、docs.discourse.org に誰かを案内するときに、そのリンクが Discourse のドキュメントではなく、限定的な API 仕様にアクセスすることになるのを忘れて、一瞬戸惑ってしまいます。
そのため、次のような言い方をしています。
本日はお集まりいただきありがとうございます。新しい Netwrix Community を使用して、ユーザーのためにどのような体験を構築できるかに関心をお寄せいただき嬉しく思います。
ドキュメントは実際には Documentation - Discourse Meta にあります。
docs.discourse.org は実際のドキュメントではなく、API 仕様です。新しいコミュニティの構築との統合について質問されたことは承知しています。残念ながら、Discourse が提供するすべての機能を示すページを案内することはできませんが、docs.discourse.org にアクセスして、可能なことの一部を把握することができます。
このシナリオで私がやっていることは、エンドポイントが存在する決定的なリストを提供できないため、「考えられることはすべて可能だと想定してください。私が Discourse が何ができるか調べて、必要に応じてそこから絞り込んでいきましょう」と伝えています。
しかし、すべての API が仕様に記載されていれば素晴らしいですよね？
さらにコンテキストを…
車を購入したのに、機能シートを渡されて「素晴らしい！これで全部ですか？」と尋ねるようなものです。
「いいえ…しかし、ボンネットを開けて、12V配線のいくつかとエンジンの周りのホースクランプをたどれば、それらが何に接続されているかを確認し、他の機能もリバースエンジニアリングできるはずです。」
確かに、このシナリオの整備士/開発者/技術に詳しい人はそうすることができます。しかし、誰もができるわけではありません 
また、開発者であっても、次のようなことはしたくありません。
- ルートが存在する可能性のある場所を確認するために Ruby を学ぶ
- 利用可能なエンドポイントのアイデアを得るためにすべての routes.rb ファイルをリバースエンジニアリングする
- 入力要件、出力のオブジェクト構造を把握するために、そのリバースエンジニアリングをさらに洗練させる
- どのプラグインを持っているか調べる
- (おそらく？Ruby は知らないので、実際には確信がありませんが) 彼らの routes.rb ファイルでも繰り返す
- …そして 6 か月後、日中の仕事とこれとの間で、回答を得る。
私はこれを愛情を込めて言っています。今日、Discourse プラットフォームの機能に匹敵するプラットフォームは存在しません。断言します。 市場で最も強力で、最も機能的で、柔軟で、費用対効果の高い製品であり、競合他社をはるかに凌駕しています。
その欠点は、堅牢性、パワー、柔軟性ではありません。実際、それらは Discourse の最大の強みの一部であり、競合製品が模倣するのに苦労したり、失敗したりするものです。
- API が優れていないということではありません。見つけるのが難しいということです。
- 採用を困難にするのは、多くのオプションを持つ管理パネルではなく、教育の欠如と、「最初の投稿のみ」のような管理設定名が、せいぜい曖昧であることです。
- カテゴリ、トピック、タグのコミュニティツールの構造の堅牢でシンプルな（そして完璧な！）実装ではありませんが、それがカテゴリである必要はなく、ブログ、製品発表ボード、またはアイデアポータルになる可能性があることを教育し、インスピレーションを与える情報が存在しないことです。そして、それらはトピックである必要はなく、ブログ、製品発表、アイデアになることができます。
これこそが、Discourse という製品が私にとって唯一欠けているものです。それは、洗練された、仕上げの詳細です。
9/10、また購入します。
「いいね！」 7
はい、より理解が深まったと思います。ありがとうございます。
以下は私の個人的な意見です。まだ、私よりも知識のある人たちと議論したわけではないので、いくつか間違っている点について指摘を受けるかもしれません。
ストーリーのドキュメントも進化しています。かなりの進歩を遂げましたが、まだまだ道のりは長いです。少しだけ要約させてください。
まず、高レベルなメンタルモデルとして、以下のように説明します。
- ドキュメントの主なエントリーポイントは、ご指摘の通りこちらです: 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のストーリーを少しずつ改善するために、小さなことができることには注意を払っていきます。具体的な質問があれば、それらをきっかけに、それまでの間により的を絞った改善を行うことができるかもしれません。
「いいね！」 5
APIの安定性に関する保証は、明確なAPIバージョニングによって対処されるべきです。
このトピックは、ドキュメントがどこに存在するかの問題ではなく、APIが どのように ドキュメント化されているかの問題です。不足しているのは、OpenAPIのような標準化された機械可読フォーマットです。
その欠如とバージョニングの欠如により、統合作業は本来よりも困難で脆弱になっています。ドキュメント化されたエンドポイントの基本的なOpenAPIスキーマでさえ、非常に役立つでしょう。
「いいね！」 3
根本的にこれはドキュメントの問題ではなく、実装の問題です。
@avdi が数年前にこれを提起しており、適切なバージョン管理された JSON/REST API を、一貫したパラメータとデータ形状で提供することが正しい進路であるという広範な内部コンセンサスがあります。
現在、私たちが提供している API は内部 API です。これは 100% 完全で網羅的ですが、扱いにくく形状が変化します。返される形状とエンドポイントはすべて、クライアントサイドの Ember アプリを駆動するために最適化されています。数ヶ月かけて進化し形状が変わるため、ミッションクリティカルなタスクに依存するのは困難です。それに基づいた構築は、必要以上に複雑です。
まったく新しいコントローラーとルートのセットは、ここで安定性の問題を解決し、REST API に適した形状を返すことを可能にします。たとえば：
/api/v0/topic/1234.json は、より「一般的な API の実践と一貫した」形状を返すことができます。
私たちのトピック JSON には、あまりにも多くの非常に複雑な「Ember クライアント専用の懸念事項」があります。
timeline_lookup、post_stream、tags_descriptions など…など…
とはいえ、これは着手するには大規模なプロジェクトであり、ロジックの重複を避けるために多くの内部再設計が必要になります。さらに、プラグインはこれをさらに複雑にします。なぜなら、それらは多くの内部動作の形状を変更し、API でも反映する必要があるからです。（assign はこれらの形状にどのような影響を与えますか？）
この冒険に着手することは確かに見えますが、近い将来ではありません。
「いいね！」 10
変更に時間がかかるのは完全に合理的だと思います。私は前職でデベロッパーリレーションズを担当していましたが、それはそれは…APIを改善された状態にするのに2年以上かかりました。考慮すべきことがあまりにも多く複雑でした（そしてエンジニアリングチームは、変更できない安定したエンドポイントを作るという考えを嫌っていました！）。
しかし、より小さな変更は、より短い期間で、時間をかけて行うこともできると思います。正直に言うと、あなたのルート（またはRubyのルート）がどのように定義されているかは調べていませんが、比較的簡単に処理できる「ローハングフルーツ」があるのではないかと推測します。例えば：
皆を代表して話すことはできませんが、たとえ説明や例がなく、レスポンスモデルが流動的であっても、現在のAPI仕様にエンドポイントが存在するだけで、大きな成果になると思います。単に何かが存在することを知っているだけで、時には戦いの半分が終わったようなものです。
「いいね！」 5
APIドキュメントはOpenAPIフォーマットですか？
https://docs.discourse.org/openapi.json
{
"openapi": "3.1.0",
"info": {
"title": "Discourse API Documentation",
"x-logo": {
"url": "https://docs.discourse.org/logo.svg"
},
"version": "latest",
...
「いいね！」 6
恥ずかしながら、今まで気づきませんでした…
@blake、ご指摘いただきありがとうございます。
「いいね！」 2