インテグレーションのベストプラクティス
統合アプリケーションの互換性と耐久性を最大限に高めるために、このページに記載されているベスト プラクティスに従うことをお勧めします。すべての注意事項がすべての統合に適用されるわけではありません。たとえば、JSON の解析は、XML 形式で API 応答を要求するアプリケーションには関係ありません。ただし、以下の点に留意することをお勧めします。
下位互換性
Infobip API は時間の経過とともに進化します。私たちは、新しい機能を追加し、新しい機能で既存の機能を改善するために懸命に取り組んでいます。そうすることで、いくつかのルールに従って下位互換性が維持されます。これらのルールに従うことで、統合が将来の API の改善で引き続き適切に機能し、これらの新機能の恩恵を受けることができます。
既存のリソースに新しいフィールドを追加する
既存の API エンドポイントに新機能を導入するために使用する方法の 1 つは、既存の要求モデルや応答モデルに新しいプロパティを追加することです。例えば：
Original response model:
{
"status": "OK",
"statusId": 1
}
Extended response model:
{
"status": "OK",
"statusId": 1,
"statusDescription": "All went well, no additional actions required"
}
リクエストモデルにプロパティを追加するときは、既存のすべての統合が問題なく機能し続けるように、フィールドがオプションであることを常に確認します。
ただし、応答モデルのプロパティに関しては、未指定のプロパティを検出したときに解析実装が中断しないようにする必要があります。これにより、API に新しい機能が追加されるたびにコードを更新する必要がなくなります。同時に、新しい機能を使用することを選択した場合は、新しいプロパティを 1 つ解析するだけで済むため、コードの更新が簡単になります。
JSON プロパティの順序
【JSON仕様】(http://www.json.org/ (opens in a new tab)) はオブジェクト内の名前と値のペアの順序を保証しないため、JSON 解析の実装もこれに依存しないでください。実際には、これは、次の JSON オブジェクトが同一であると見なされることを意味します。
Example object:
{
"status": "OK",
"statusId": 1
}
Equivalent object:
{
"statusId": 1,
"status": "OK"
}
API 実装は、上記の例のオブジェクトのいずれかを互換的に返すことができ、クライアント コードによって同じように扱われる必要があります。幸いなことに、json 解析が言語のネイティブ機能または確立された解析ライブラリの 1 つに委任されている場合、これはそれらの実装によって適切に処理されているはずです。
日付形式
API は通常、定義済みの統一された形式で日付を返します。特定のエンドポイントの詳細については、専用のドキュメントページを参照してください。デフォルトで使用される形式は次のとおりです。
yyyy-MM-dd'T'HH:mm:ss.SSSZ
この形式はエンコードされ、タイムゾーン情報が必要であることに注意してください。これは、一見異なる 2 つの日付/時刻文字列が、実際には同じ時点を表していることを意味します。
2017-07-20T06:47:45.777+0000
2017-07-20T07:47:45.777+0100
API から受信した日付を解析するときは、タイム ゾーンを考慮する必要があります。ベスト プラクティスは、API から受信した文字列を、その時点の言語のネイティブ表現に変換することです。その後、処理でき、選択したタイムゾーンと形式がユーザーに表示されます。重要な注意: API から返される日付と時刻が常に事前定義されたタイム ゾーンにあるとは思わないでください。代わりに、返されたタイム ゾーン情報を使用する必要があります。
エラーの防止
アプリケーションが API の将来の開発と引き続き互換性があることを確認するだけでなく、バグがないようにすることも重要です。そのために、考慮すべき一般的な問題をいくつか紹介します。
要求本文のコンテンツの種類
専用の ドキュメントページで (opens in a new tab)説明されているように、メッセージ本文データを含むすべての要求には、Content-Type ヘッダーを含める必要があります。サポートされているコンテンツ タイプは application/json と application/xml です。いずれの場合も、要求で送信する本文データは、指定された Content-Type ヘッダーと一致し、有効である必要があります。
JSON コンテンツ
JSON を使用する場合は、データを 有効な JSON オブジェクト (opens in a new tab) にシリアル化してください。特に、文字列値に注意してください。二重引用符 (") を含めると文字列の終わりがマークされるため、二重引用符を含めることはできません。二重引用符が必要な場合は、バックスラッシュ (\) でエスケープしてください。さらに、JSON オブジェクト内の名前と値のペアがコンマ (,) で区切られていることを確認してください。標準のシリアル化ライブラリの一部を使用することを選択した場合は、すべて既に実装されているはずです。
{
"stringProperty": "properly \"quoted\" string value",
"numberProperty": 47,
"booleanProperty": true,
"nullProperty": null
}
{
"stringProperty": "properly "quoted" string value"
"numberProperty": 47
"booleanProperty": true
nullProperty: null
}
XML コンテンツ
XMLを使用している場合は、オブジェクトが有効なXMLに適切にシリアル化されていることを確認してください。具体的には、すべてのタグを閉じることと、正しい順序で閉じていることを確認します。また、タグでは大文字と小文字が区別されます。繰り返しになりますが、定評のあるXMLシリアライゼーションライブラリまたはネイティブ言語関数がこれらすべてを処理する必要があります。
<request>
<outerProperty>
<nestedProperty>Some Value</nestedProperty>
</outerProperty>
<flatProperty>47</flatProperty>
<emptyProperty/>
</request>
非推奨の標準
業界標準は、時間の経過とともに非推奨になる可能性があります。その代表的な例が、SSL証明書でのSHA-1ハッシュ関数の使用です。 セキュリティと承認のドキュメント (opens in a new tab)セクションに記載されているように、HTTPS プロトコルを使用して API に接続することを強くお勧めします。SHA-1 は廃止され、最新のテクノロジ スタックとアプリケーションからサポートが削除されているため、API は新しいアルゴリズムを使用して作成された証明書によって署名されています。それを認識するために、スタックもそれらを使用する必要があります。
エラー処理
通常の統合操作でも、API からのエラー応答が発生することが予想されます。エラーが発生した場合は、API 応答に認識可能でわかりやすいメッセージを入力しようとします。このようなシナリオでは、コードで API 応答を分析し、適切な方法で対応することをお勧めします。
HTTP 応答コード
すべての HTTP 応答コードとその意味 (opens in a new tab) のリストに慣れておく必要があります。すべてのリクエストに適切なステータスコードを返すよう努めます。返された状態コードを調べることは、API 応答への対応方法を決定するために最初に実行できることです。
一般に、200の範囲(200から299まで)のステータスはすべて成功と見なされ、追加の反応は必要ありません。
状態コードが 400 番台 (400 から 499) の応答は、要求に何か問題があったことを示します。まったく同じリクエストをすぐに再度送信すると、同じエラーが発生するため、お勧めできません。代わりに、返された特定のステータスを分析し、それに応じて調整できます。たとえば、ステータス 400 (Bad request) が返された場合は、Content-Type ヘッダーを再確認し、要求本文データが適切にシリアル化されていること、および API に送信されるデータが専用の API エンドポイントのドキュメント ページから指定された要求モデルに対応していることを確認する必要があります。一方、ステータス 404 (Not found) の受信は、要求された API エンドポイントまたは正確なリソースが存在しないことを意味します。この場合、専用のドキュメントページで定義されている API エンドポイントのパスを再確認してください。
500 番台 (500 から 599) のステータス コードは、要求は有効であるが、API 側でエラーが発生したことを示します。特定のステータスによっては、エラーが一時的なものである場合があるため、同じ要求を再試行すると、異なる結果が生じる可能性があります。
調整
要求で発生する可能性のある特定のエラーの 1 つは、調整エラーです。通常、HTTP 状態コード 429 (要求が多すぎます) で示され、事前定義された時間内に特定のエンドポイントに対して要求が多すぎる場合に発生します。
Infobip API には、すべてのエンドポイントに対して 1 つの調整ルールがあるわけではありません。代わりに、専用のルールがある場合があります。特定のものを見つけるには、専用のドキュメントページに戻ります。たとえば、必要な数の送信SMS要求を作成できます。これらのエンドポイントはトラフィックに使用されると見なされ、制限はありません。一方、送信されたSMSログのフェッチは、一括レポートに使用する必要がある管理エンドポイントです。そのため、時間枠で許可される要求の数には制限があります。それ以降の get logs 要求はステータス コード 429 を受け取り、十分な時間が経過するまで実行されません。
API 要求の 1 つが調整された場合は、しばらく待ってから再試行できます。ただし、再試行の回数が多すぎると、さらに多くの要求が調整される可能性があるため、注意してください。再試行ロジックを実装するときは、再試行回数の制限を含め、調整された要求の全体的な数を監視してください。調整される要求が多すぎる場合は、サポートされていない方法で API を使用している可能性があります。
コーディングの実践
これは、APIを使用しながら開発中に例をコーディングして使用する場合のベストプラクティスです。
クエリ パラメーターと URL エンコード
Infobip API Developer Hub (opens in a new tab) のクエリ パラメーターの例とコード例 (SMS ログの取得 (opens in a new tab)など) は、URLエンコードされていません。
これにはいくつかの理由があります。まず、コード例を人間が読めるようにする必要があります。第二に、HTTP呼び出しを行う多くの言語とライブラリは、クエリパラメータに明示的なURLエンコーディングを必要としません-それは「内部で」行われます。
明示的な URL エンコードを必要とするシステム/ライブラリ/言語を使用する場合は、自分で行う必要があります。幸いなことに、ほぼすべての言語で十分なサポートがあります。