すべてのAPIエンドポイントの完全なドキュメントが存在しない理由がわかりません。元のドキュメントは2014年12月に一般公開されましたが、それから6年が経った今でもドキュメントは半端な状態のままです。
なぜでしょうか？優れたドキュメントの欠如と、APIをリバースエンジニアリングするよう促すことは、APIを利用しようとする開発者にとって大きな障壁となっています。
敬具
不満を持つ開発者
具体的に、どのような点で困っているのか、あるいは不足していると感じているのか、例を挙げていただけますか？
これはタイムリーな話題です。私のフォーラムに「非推奨の認証方式を使用した API リクエストを検出しました」という警告が表示されています。
現在使用すべき正しい方法と、フォーラム管理者の視点での実装手順を教えてください。
私が調べたところ、古いスレッドで GitHub へのリンクが貼られていましたが、技術に詳しくない私にとって、コードへの言及は役立ちません。誰か平易な言葉でアドバイスをいただけないでしょうか？
適切な API 認証については、ドキュメントの一番上に記載されています。簡単に言うと、URL パラメータの代わりに HTTP ヘッダーを使用して API キーとユーザー名を指定する必要があります。
@justin 私の具体的な例は、Discourse API の Python ラッパーを徐々にリリースしているのですが、適切なドキュメントが不足していることに圧倒されています。すべてのエンドポイントを一つずつ手動でテストしなければならない状況ですが、その多くはドキュメント化されていないか、誤ってドキュメント化されています。
ドキュメントの冒頭には、API が完全にドキュメント化されていないことが明記されています。なぜなのでしょうか？
Reverse engineer the Discourse API をご覧ください
なぜビーチのすべての砂粒が「完全に文書化」されていないのでしょうか？ 
興味本位で伺いますが、なぜ必要なものだけを対応し、新しい非対応要件に直面した時点でリバースエンジニアリングしないのでしょうか？100% 対応を目指すよりもずっと簡単ですし、決して使われない呼び出しをラップしても無意味です。特に、対応すべき対象が常に変化している場合を考えると、あなたの仕事を楽にしませんか？
これはリバースエンジニアリング可能だと理解しています。ただ、これをしなければならないのは少し苛立たしいですね。API は人間によって作成されたものであり、その仕組みを知っているはずです。なぜその人たちがそれを文書化して、他の人にも情報を提供しないのでしょうか？
これは大きな要求だとは思いません。どんなプロジェクトでも、良いドキュメントは不可欠です。
それが現在の計画です。開発ブランチには、ドキュメント化されたすべてのエンドポイントを私のリポジトリにミラーリングしてあります。ここで、リバースエンジニアリングを開始せざるを得ない段階にきました。
すでに GitHub - discourse/discourse_api_docs: Discourse API Documentation · GitHub への貢献を始めていますが、これほど確立されたプロジェクトでなぜこれが必要なのか、本当に疑問に思っています。
あらゆることと同様、これはリソースと優先順位の問題です。API の表面積は非常に広大です。技術的には、すべてが API 経由でアクセスされるため、リバースエンジニアリングが機能します。私たちは限られたエンジニアリング時間をドキュメント作成よりも、修正、機能追加、パフォーマンス向上などに注力することを選びました。当社の製品方針は主に顧客とコミュニティによって決定されます。私の知る限り、顧客から「100% の API ドキュメントカバレッジ」を求められたことはありません。顧客から不足している点や不明確な点について問い合わせがある場合、私たちはそれに対応して追加しています。したがって、100% のカバレッジは優先事項ではありませんでした。
現時点では、API ドキュメントは手動でキュレーションされています。これは明らかに持続可能な方法ではありませんが、現状ではこれが私たちの手元にある唯一の方法です。API ドキュメントシステムをプログラムで生成されるようにリファクタリングすることは「TODO」項目として残っていますが、現在特定のリリースに割り当てられておらず、完了までのタイムラインも存在しません。