有効期限のないAPIキーの問題点
何年も前に発行され、一度もローテーションされず、今も有効なキーは、便利なものではありません。何年も誰も実際に確認していない負債です。
独自のレスポンス形式への反論
APIがなぜシンプルでフラットなJSON構造ではなく、入れ子になった独自のオブジェクトモデルを返すのかと尋ねてみると、正直な答えが技術的なものであることはめったにありません。独自の形式にしても、検索が速くなったり正確になったりするわけではありません。変わるのは、応答を置き換えにくくなることです。コードが扱いを覚えるフィールド名、入れ子の階層、独自のステータスコードのひとつひとつが、アプリケーションに組み込まれたベンダー固有の知識の小さなかけらになるからです。
当社はそれが逆だと考えています。レスポンス形式が表すべきなのはデータであり、ベンダーではありません。座標、住所、オフセット、標高は、誰がリクエストに答えても同じ概念なので、それらに対して返す形式も、概念そのものと同じくらいシンプルであるべきです。当社のホストのうち17個が他のプロバイダー自身のAPIとまったく同じレスポンス形式を返すのもそのためです。データは当社のものですが、形式はお使いのコードがすでに理解しているかもしれないものです。そもそも、その形式は当社が発明すべきものではないからです。
独自形式には、基になるデータとは無関係で、プロバイダーの社内の経緯とだけ関係する奇妙な点が積み重なりがちです。社内の移行のためにフィールド名が変更され、古い名前は誰も削除したがらない非推奨のエイリアスとして残り続けます。あるステータスが、あるエンドポイントでは文字列、別のエンドポイントでは数値コードで表されるのは、何年も離れた時期に別々のチームが作ったからです。どれも悪意があるわけではありません。形式が外部の標準に照らして設計されることがなく、企業自身の変化し続けるコードベースだけに合わせて作られると、こうなるというだけのことです。
解決策は複雑ではありません。シンプルな構造を選び、一度ドキュメント化し、安定して維持することです。当社は自社のネイティブエンドポイント全体でそれを実践しており、互換ホストではさらに一歩進んで、他のプロバイダーの形式に正確に合わせています。そのため、すでにその形式を解析しているコードベースは、ベースURLとキー以外に一切変更する必要がありません。これは見た目以上に大きな約束です。合わせている形式に扱いにくいフィールド名や一貫性のない入れ子があっても、当社はその扱いにくさをそのまま残すということです。互換ホストの価値はすべて、改善ではなく忠実さにあるからです。
独自形式は、プロバイダーが時間をかけてより豊富なデータを追加する余地を与えるものとして擁護されることがあります。当社は、豊富さのために見慣れない形式が必要だとは考えていません。標高やIPの脅威情報のようなオプションのフィールドは、置き換えではなく追加として標準の応答と並べて置けます。そうすれば、それを求めない呼び出し側はそれを避けて解析する必要がなく、求める呼び出し側は新しい形式を覚えることなくそれを受け取れます。
これは技術的な好みとしてのJSONの書式の話ではありません。形式の決定によるコストを誰が負担するかという話です。独自形式は、応答を読む必要があるすべての顧客にそのコストを負わせます。シンプルな形式や既存に合わせた形式は、予測可能な状態を保つ設計作業という形で、そのコストを当社が負います。コストはそこが負うべきものです。