JSON APIとXML APIの違い

JSONとXMLのどちらを選ぶかも、クライアントとAPIの間の契約にかかわる問題です。クライアントは、成功、バリデーションエラー、認証の失敗、レート制限、一時的なサーバーエラーを区別して扱う必要があります。JSONかXMLかでHTTPのセマンティクスが変わることはありません。また、IPv4/IPv6の値は、IPv4の長さを前提にせず、そのまま保持しなければなりません。

応答の扱い方

Content-Type、ステータスコード、ドキュメントに記載されたフィールド、クォータを検証します。HTTP 429は別に扱い、Retry-Afterが返された場合はそれに従い、上限付きの指数バックオフにジッターを組み合わせてください。リトライの前には冪等性も考慮します。リクエストID、ステータス、レイテンシはログに残しますが、APIのシークレットは決して記録しないでください。

JSONとXMLの特徴

JSONは一般的なオブジェクトや配列のデータモデルに自然に対応し、たいていはコンパクトです。XMLは属性や名前空間に対応し、成熟したスキーマ関連のツールがそろっています。どちらかの形式が常に速い、あるいは正しいと決めつけず、APIの仕様とエコシステムに合わせて選びましょう。リクエストの例と最新の仕様は、2IPのAPIで確認できます。