コンテンツの種類

NTT CPaaSのAPIは、いくつかのコンテンツの種類 に対応しています。APIの大部分のリクエストとレスポンスは、application/json または application/xml のどちらかの形式となります。そのため、少し時間を取って、事前にJSON 形式 ならびにXML 形式 の詳細について確認するようにしてください。

なお、メール送信など一部のAPIエンドポイントでは、multipart/form-dataが使用されるため、特定のエンドポイントを使うことを検討している場合は、エンドポイントについて詳述しているドキュメントの中で、それらについて詳しく説明しているページを参照しておくことをお勧めします。

レスポンスのコンテンツの種類の指定

選択したいAPIレスポンスのコンテンツの種類は、次の2つの方法のいずれかで指定できます。

Acceptヘッダー [#accept-header-specifyresponse-content-type]

1つ目は、標準のAccept HTTPヘッダーを使用する方法です。

リクエスト例：

レスポンス例：

パスの拡張 [#path-extension-specifyresponse-content-type]

何らかの理由でAPIコールのAcceptヘッダーを変更できない場合、特定のコンテンツの種類を指定する別の方法があります。それは、リクエストパスに、選択したいコンテンツの種類に対応する拡張子を付加することです。

下記のリクエストを送信すると：

以下のようなXML 形式のレスポンスが返されます：

レスポンスのコンテンツの種類の指定

リクエスト本文のコンテンツの種類は、リクエストのContent-Typeヘッダーで指定する必要があります。特に指定がない場合、API エンドポイントは application/json または application/xml のどちらの形式のコンテンツにも対応します。

例えば、SMSメッセージはJSONまたはXML形式で作成できますが、その場合はContent-Typeヘッダーをそれぞれの形式に合わせて記述する必要があります：

最後に、デフォルトではAPIのレスポンスは送信されたコンテンツと一致することにご注意ください。但し、リクエスト本文データの送信に使用したコンテンツとは異なる種類のコンテンツでAPIのレスポンスを受け取りたい場合は、Acceptヘッダーを明示的に設定することで、この動作を変更することができます。これは、multipart/form-data形式でメールを送信する際、レスポンスには別のコンテンツの種類が望ましい場合に役立ちます：

上記のリクエストは、JSON形式のレスポンスを生成します。

Bad Requestエラー

APIは、よく起こるエラーを見分け、適切な方法でレスポンスを返そうとします。例えば、HTTPメッセージの本文データに問題がある場合、APIはHTTPステータス400 (Bad Request) を返し、レスポンス本文は次のような内容になる可能性があります：

このレスポンスにはいくつかの原因が考えられますが、以下に一般的な原因をいくつか挙げます：

• Content-typeヘッダーが抜けている
• Content-typeが送信した本文データと一致しない
• 送信した本文データがJSON形式またはXML形式に準拠していない

但し、認識されないパラメーターがAPIリクエストの本文データに含まれている場合、それらのパラメーターは、リクエストの形式が適切である限り、単に無視されるだけで、リクエストが自動的に失敗することはありません。このため、対象となるAPIエンドポイントについて詳述しているドキュメントを参照し、そこに定義されている有効なパラメーターのリストを確認するようお勧めします。

レスポンスの解析

APIのレスポンスを解析する際は、必ずJSONまたはXMLの仕様に準拠してください。それぞれに固有の細かい仕様があります。例えば、JSON 形式では、オブジェクト内の名前と値のペアの順序は保証されません。そのため、JSON 形式の API レスポンスを解析する際は、プロパティの順序に決して依存しないようにしてください。

使用する言語によっては、JSON / XMLの解析機能が標準でサポートされている場合もあれば、それを処理する外部ライブラリを使用する必要がある場合もあります。