有効期限のないAPIキーの問題点
何年も前に発行され、一度もローテーションされず、今も有効なキーは、便利なものではありません。何年も誰も実際に確認していない負債です。
ドキュメントの質が機能の数より重要な理由
40個のエンドポイントを並べた料金ページは、15個を並べたページより高機能に見えます。しかし、それは多くの場合、警告のサインでもあります。エンドポイントを作ることは、それを使えるようにする作業のほんの一部にすぎません。残りはドキュメントです。わかりやすいパラメーターの説明、実際のリクエストとレスポンスの例、エッジケースについての正直な注記、そして何か問題が起きたときに何が起こるのかの平易な説明です。40個のエンドポイントでその作業を省けば、技術的には存在していても実用上はほとんど存在しないに等しい機能が40個できあがります。
私たちは、多くのものを不十分に文書化するより、少ないものをしっかり文書化したいと考えています。APIを評価する開発者が最初に機能一覧を読むことはめったにありません。ドキュメントを読み、例のリクエストを試し、その例が書かれているとおりに実際に動くかどうかで、最初の数分のうちに会社全体についての印象を形成します。動かなければ、マーケティングページの機能の数はもはや意味を持ちません。読み続けるために必要な信頼がすでに失われているからです。
私たちにとって良いドキュメントとは、あいまいな約束ではなく、いくつかの具体的なことを意味します。認証について、プロバイダーが好む方法だけでなく、受け付けるすべての方法をはっきり示して説明すること。レート制限を「十分な上限が適用されます」ではなく、実際の数値で示すこと。エラーコードを、それぞれの実際の原因とともに一覧にし、失敗したリクエストをデバッグしている開発者がステータスコードだけから推測するのではなく、ドキュメントで答えを見つけられるようにすること。どれも追加のエンジニアリングを必要としません。必要なのは、それをわかりやすく書き留めることが本当の製品に付随する任意の雑務ではないと、誰かが決めることです。
そこそこ程度のドキュメントには、積み重なるコストもあります。ドキュメントで答えを見つけられない開発者はサポートチケットを作成し、その1つの質問を解決するために、機能の構築にすでに費やしたエンジニアリングの時間に加えてスタッフの時間がかかります。同じわかりにくい段落につまずく顧客が十分な数になれば、薄いドキュメントで済ませた「節約」はすぐにマイナスに転じます。わかりやすいドキュメントは、APIの上に重ねるあれば嬉しいおまけではありません。わかりにくい段落が生み出すサポートの負荷を計算に入れれば、そちらのほうが安上がりなのです。
また、ドキュメントの品質は、見込み客が連携に踏み切る前に実際に評価できる数少ないシグナルの1つだと考えています。プロバイダーの稼働率の履歴を5分で簡単にテストすることはできませんし、先に連携しなければデータの精度を十分に判断することもできません。しかし、5分あればドキュメントを読んで、それを書いている会社が製品をわかりやすく説明できるほど理解しているのか、それともドキュメントが営業ページ向けに作られた機能一覧に後から付け足したもののように読めるのかを判断できます。
長い機能一覧を書くのは簡単です。開発者が最初の試みで実際にそれをもとに構築できるドキュメントはそうではありません。そしてその違いこそが、ドキュメントのほうが重要である理由です。