有効期限のないAPIキーの問題点
何年も前に発行され、一度もローテーションされず、今も有効なキーは、便利なものではありません。何年も誰も実際に確認していない負債です。
私たちがエラーコードを隠さずに公開する理由
APIリクエストの失敗は、それだけで誰かの一日にとって嫌な瞬間です。返ってきたエラーコードがどこにも説明されておらず、デバッグする開発者が、400がパラメーターの形式誤りなのか、必須フィールドの欠落なのか、それとも無関係な3つの問題と同じステータスコードをたまたま共有しているまったく別の何かなのかを推測しなければならない場合、事態はさらに悪くなります。文書化されていないエラーは、単に不便なだけではありません。5分で済む修正を終わりの見えない調査に変え、本来存在すべきページを読めば避けられたはずのサポートチケットに行き着くこともあります。
当社はエラーコードをエラーのドキュメントでわかりやすく公開しており、それぞれが実際に何を意味し、何が原因になることが多いかを記載しています。あわせて、リクエストが失敗するほかの原因を説明する認証とレート制限のページも用意しています。目標は、何か問題が起きたときに、答えがページひとつ先にあることです。当社のシステムが具体的に何をしたかにきれいに対応するかどうかわからない、一般的なHTTPステータスコードの慣例に基づいた推測であってはなりません。
エラーの詳細を隠すこと(不十分なドキュメントによる意図しないものも含む)は、一見もっともらしい直感から生まれることがあります。リクエストが失敗した理由を正確に明かすと、理論上はAPIの弱点を探っている人の手助けになりかねない、というものです。実際には、この懸念が実際のコストに見合うことはめったにありません。エラーコードに遭遇する人の圧倒的多数は、攻撃対象領域を調べている敵対者ではなく、自分の連携を修正しようとしている正当な開発者です。ほかの全員にとっての明確さを犠牲にして、まれな悪意ある人物を基準にエラーのドキュメントを最適化するのは、トレードオフを逆に捉えています。
エラーコードを明確に公開することには、設計上の規律という利点もあります。内部の一貫性が求められるのです。すべてのエラーコードをわかりやすい説明とともに文書化しなければならないとなると、書いた本人のエンジニアしか完全には理解していない、場当たり的で重複したエラー条件が積み重なることがはるかに難しくなります。ドキュメントを書くことは、ひそかにエラー処理そのもののコードレビューにもなります。明確に説明しにくいエラーは、多くの場合、そもそもその根本的な条件が十分に考え抜かれていなかったことの表れだからです。
割り当てに関する失敗は、エラーコードだけでなくレスポンスヘッダーを通じて、関連した形で扱われます。すべてのレスポンスには、割り当ての上限、使用量、無料割り当ての残り、ネットワークの使用量、クレジットの残高、リセット時刻が含まれているため、割り当てが原因で失敗したリクエストは、正体不明のステータスコードではまったくありません。それはリクエストを送る前に確認できた数字であり、失敗したレスポンスから直接読み取ることもできる数字です。
これでリクエストが失敗したときのいら立ちがなくなるわけではありません。ただ、そのいら立ちは、実際の答えとともにドキュメントで終わるべきだということです。サポートの順番待ちに持ち込まれたり、まったく別のAPIのステータスコードが似たような状況で何を意味していたかについて、古いフォーラムの投稿をあちこち推測しながら探し回ったりすることになってはなりません。