連携に関するベストプラクティス

連携するアプリケーションの互換性と耐久性を最大限に高めるためには、このページに記載されているベストプラクティスに従うことが推奨されています。すべての注意事項が必ずしもすべての統合に当てはまるわけではありません。例えば、XML形式でAPIレスポンスをリクエストするアプリケーションには、JSONの解析に関する注意事項は当てはまりません。但し、以下の点に留意することをお勧めします。

下位互換性

NTT CPaaS APIは、時間の経過とともに進化を続けています。当社は、新機能の追加や既存機能の改善に尽力しています。その際、いくつかのルールに従って、下位互換性を維持するようにしています。これらのルールを順守することで、将来的なAPIの改善後も、連携したアプリケーションが正常に機能し続け、新機能の恩恵を確実に受けられるようになります。

既存リソースへの新しいフィールドの追加

既存のAPIエンドポイントに新機能を導入する方法の1つとして、既存のリクエストおよび／またはレスポンスモデルに新しいプロパティを追加することが挙げられます。例えば：

json

 
    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仕様 (opens in a new tab) では、オブジェクト内の名前と値のペアの順序は保証されていないため、実装しているJSON解析機能も、その順序に依存すべきではありません。実際には、これは以下のJSONオブジェクトが同一と見なされることを意味します：

json

 
    Example object:
    {
        "status": "OK",
        "statusId": 1
    }
    
    Equivalent object:
    {
        "statusId": 1,
        "status": "OK"
    }

APIの実装では、上記の例で示したいずれかのオブジェクトが返される場合がありますが、クライアントコードではそれらをすべて同じように扱う必要があります。幸いなことに、jsonの解析がお使いの言語のネイティブ機能または広く使われているいずれかの解析ライブラリに依存している場合、それらの実装によって適切に処理されているはずです。

日付形式

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から受け取った文字列を、お使いの言語でその時刻を表す形式に変換することです。そうすることで、データを適切に処理し、ユーザーに対して希望するタイムゾーンや形式で表示することができます。

備考Do not expect that the date and time returned from API will always be in a predefined time zone. Instead, you should use the returned time zone information.

エラーの防止

アプリケーションが今後開発が進むAPIの更新版とも互換性を保ち続けるようにすることに加え、バグのない状態を維持することも重要です。その一助となるよう、ここでは留意すべき一般的な問題をいくつか紹介します。

リクエスト本文のコンテンツの種類

メッセージ本文のデータを含むすべてのリクエストには、Content-Typeヘッダーを含める必要があります。サポートされているコンテンツの種類は、application/json と application/xml です。いずれの場合も、リクエストで送信する本文データは、指定されたContent-Typeヘッダーと一致し、有効なものでなければなりません。

JSONコンテンツ

JSONを使用することを選択した場合、データが有効なJSONオブジェクト (opens in a new tab) としてシリアライズされていることを必ずご確認ください。特に、文字列の値には注意が必要です。文字列には二重引用符 (") を含めないようにしてください。それを含めると、文字列の末尾を示すことになってしまいます。二重引用符が必要な場合は、バックスラッシュ (\) でエスケープしてください。さらに、JSON オブジェクト内の名前と値のペアは、コンマ (,) で区切られていることも確認するようにします。標準のシリアライゼーションライブラリをいずれか使用することを選択した場合、これらはすべて既に実装されているはずです。

REQUEST SAMPLES

 
    {
      "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シリアライゼーションライブラリまたは言語固有の関数を使用すれば、これらすべてが適切に処理されるはずです。

xml

 
    <request>
      <outerProperty>
        <nestedProperty>Some Value</nestedProperty>
      </outerProperty>
      <flatProperty>47</flatProperty>
      <emptyProperty/>
    </request>

非推奨の標準

業界標準は、時間の経過とともに非推奨となる可能性があります。その代表的な例が、SSL証明書におけるSHA-1ハッシュ関数の使用です。セキュリティと認証について詳述しているドキュメントの該当セクション (opens in a new tab)に記されている通り、当社のAPIへの接続にはHTTPSプロトコルの使用を強く推奨します。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 (TOO_MANY_REQUESTS) で示され、構成されたレート制限内で特定のエンドポイントに対してリクエストを過剰に行うと発生します。

NTT CPaaSのAPIでは、トークンベースのレート制限を採用してリクエストの頻度を制御しています。エンドポイントごとにスロットリングの構成が異なる場合がありますので、適用される制限を確認するには、各エンドポイントについて詳述しているAPIドキュメントをご参照ください。

レート制限の種類

APIエンドポイントは、次のレート制限メカニズムの1つまたは両方によって保護できます：

時間ベースのレート制限：固定時間枠内のリクエスト数を制限します。例：10秒あたり100件のリクエスト
トークンベースのレート制限：安定した補充レートを維持しつつ、バースト処理を可能にするトークンバケットアルゴリズムを採用しています。例：バースト処理能力は5リクエスト、補充レートは1秒あたり1リクエスト

スロットリングされたリクエストの処理

APIリクエストのいずれかがスロットリングされた場合は、指数関数的バックオフとリトライロジックを実装することをお勧めします。リトライする前に短時間待機し、スロットリングされたレスポンスが返されるたびに待機時間を徐々に長くするようにします。但し、リトライ回数が多すぎると、さらに多くのリクエストがスロットリングされる原因となるため、注意が必要です。

リトライロジックを実装する際、次のことを必ず行うようにしてください：

リトライ回数の制限を含めるようにします
リトライ間の指数バックオフを実装するようにします
スロットリングされたリクエストの総数を監視するようにします
ステータス番号が429のレスポンスにRetry-Afterヘッダーが含まれている場合、そこに記載された時間を確認して、いつリトライすべきかを把握するようにします

あまりにも多くのリクエストが継続的にスロットリングされる場合は、APIがサポートされていない方法で使用されているか、リクエストのパターンを最適化する必要がある可能性があります。

コーディングに関するベストプラクティス

ここでは、当社のAPIを使用する際の参考になる、開発環境でのコーディングやサンプルコードの使い方に関するベストプラクティスについて説明します。

クエリパラメーターとURLエンコーディング

NTT CPaaS API開発者ハブ (opens in a new tab)に掲載されているクエリパラメーター例とコード例 (例：SMSログの取得 (opens in a new tab)) は、URLエンコードされていません。

これにはいくつかの理由があります。第一に、コード例を人間が読みやすいものにしておくためです。第二に、HTTPコールを処理する多くの言語やライブラリでは、クエリパラメーターに対して明示的なURLエンコーディングを行う必要がなく、内部で自動的に処理されているからです。

明示的なURLエンコーディングが必要なシステム／ライブラリ／言語を使用する場合、ユーザー自身でエンコードを行う必要があります。幸いなことに、ほぼすべての言語でそのための支援機能が豊富に用意されています。