今月のリリース:ジオコーディング、IP、タイムゾーンなど
APIの最近の取り組みのまとめです:新しい互換ホスト、より高速なタイムゾーンと標高の検索、ダッシュボードの機能、割り当ての見やすさの向上。
すべてのエンドポイントで、よりすっきりしたエラー形式に
エラーレスポンスはAPIの付け足しではなく、成功時のレスポンスと同じくらい、あらゆる連携が依存している契約の一部です。私たちはMy Geocodeのすべてのネイティブエンドポイントでエラー形式を標準化しました。そのため、APIのどの部分で発生したかに関係なく、失敗は同じ形になります。
リクエストが失敗した理由が、パラメーターの欠落、無効なキー、割り当ての使い切り、不正な形式の座標のいずれであっても、レスポンスは単一の予測可能な構造に従います。この一貫性により、1つのエンドポイントに対して一度書いたエラー処理のコードは、エンドポイントごとに別の処理ロジックを用意しなくても、他のすべてのネイティブエンドポイントで同じように動作します。
割り当てに関連する失敗は特に取り上げておく価値があります。稼働中の連携が遭遇する失敗の中で最も一般的な種類だからです。リクエストがキーまたはネットワークの割り当てを超える場合、レスポンスはそのことを明確に示します。また、すべてのレスポンスにすでに含まれている割り当てヘッダー(X-Quota-Limit、X-Quota-Used、X-Quota-Free-Remainingなど)によって、失敗したリクエストの前にどれだけの余裕があったかが正確に分かります。この組み合わせにより、クライアントは推測することなく、レスポンスだけで割り当ての問題を認証の問題や不正なリクエストと区別できます。
互換ホストは、この標準化の意図的な例外であり、それには十分な理由があります。互換ホストの目的はそもそも、他のプロバイダーのリクエストとレスポンスの形式を正確に再現することであり、そこにはエラーの見た目も含まれます。Bing Maps REST Services向けの形式で送られたリクエストが失敗した場合、エラーはBing独自のエラー形式で返されます。成功でも失敗でもその形式に正確に合わせることこそが、互換ホストの存在意義だからです。そこでエラーを標準化してしまえば、ホストが提供するために存在する互換性そのものが損なわれます。
ネイティブエンドポイント向けに構築されたものであれば、このすっきりした形式によって、エラー処理の記述と保守が目に見えて簡単になるはずです。解析処理は1つ、想定するフィールドも1セットで済み、/v1/forward、/v1/reverse、/v1/ip、/v1/timezone、/v1/elevation、/v1/autocomplete、/v1/postcodeのいずれでも挙動は一貫しています。
フィールド名や一般的な原因を含むエラー形式の完全なドキュメントは、/docs/errors/でご覧いただけます。現在の連携でネイティブエンドポイントごとに別々のエラー処理の分岐がある場合は、それを1つにまとめる良い機会です。