三菱UFJ銀行 API事務局です。
今回の記事では、 「APIの設計思想について」でご紹介した当行APIで提供しているサービスの粒度やURI（エンドポイント）の考え方に関連して、APIのレスポンスデータ設計についての考え方や開発時に工夫したポイントなどを紹介します。一般的なデータフォーマットの設計に加え、可用性を重視して設計を進めました。
１． Web APIにおけるレスポンスデータ設計時のトレンド
Web APIはHTTPプロトコルで通信されるのが一般的です。APIのレスポンスデータは、利用する開発者がわかりやすい、統一性のある設計にする必要があります。レスポンスデータの形式としては、XMLやJSONが指定されることが多く、JSONは通信時のデータ量がXMLより軽量で、表記がわかりやすいことから主流となっています。Web APIを利用するクライアント側の開発はJavaScriptで実装されることが一般的なので、JavaScriptのオブジェクト表記法であるJSONは、関数を用いて容易にJavaScriptのオブジェクトへの変換が可能である点においても秀でています。またエラー情報は、HTTPステータスコードで表現されたり、それに加えてレスポンスデータの中で定義されたエラーオブジェクトによって、よりくわしく表現されたりします。
設計時の詳細な観点は、表１をご参照ください。
表１．レスポンスデータ設計時の一般的な観点
| 観点 | 説明 |
|---|---|
| プロトコル | Webサーバからデータを取得するための基本プロトコルであるHTTPや、その通信を暗号化したHTTPsが利用されている HTTPメソッドは全部で8つあるが、APIでは主にGET（参照）・POST（登録）・DELETE（削除）・PUT（更新）の4つがリクエストで使用されている |
| データ形式 | 最近の主流はJSONであり、それ以外ではXMLなども利用されている |
| データ形式の指定方法 | HTTPリクエストではacceptを用いて指定する （例）Accept：text/html, application/json HTTPレスポンスではContent-Typeに設定されている （例）Content-Type：application/json |
| データボディ部の内部構造 | APIのアクセス回数が少なくて済むような設計 （例：1度のアクセスで多くの情報をとってくる） ユースケースに適した設計 （例：アクセス数の少なさと必要な情報の取得を両立させる） |
| 正常・エラー情報 | レスポンスヘッダに含まれるステータスコードで表す |
２． 当行APIのレスポンスデータ設計にて工夫したポイント
当行では表1で紹介した主流な設計に加え、全国銀行協会（以下、全銀協）で推奨されている（※）プロトコルやデータ形式の標準に則り設計しました。また、開発当初、一部のAPI利用事業者にベータ版を公開して外部の声を取り入れつつ、以下の（ⅰ）～（ⅳ）の観点を重視してレスポンスデータを設計しました。
※全銀協では、オープン・イノベーションが起こりやすい環境の実現を目指すため、開発標準を示しており、その中でいくつかの仕様が推奨されています。
以下リンクは外部サイトへ遷移します。
- 参考資料：
- 全国銀行協会（2018年12月25日時点）
オープンAPIのあり方に関する検討会報告書 － オープン・イノベーションの活性化に向けて －
（ⅰ）プロトコルについて
プロトコルはHTTPsを使用しています。HTTPメソッドについて、照会や申請を行うことができる当行APIではGETメソッドとPOSTメソッドを実装しています。
（ⅱ）データ形式について
データ形式はJSONを使用しています。
一般的に、多くのWeb APIはRESTで公開されています。当行内のシステム間連携はSOAPも使用していますが、現在のデファクトスタンダードであるREST、およびJSONを採用しました。
（ⅲ）HTTPレスポンスデータの内部構造
HTTPレスポンスデータは、ステータス行やヘッダーフィールドからなるヘッダ部と、メッセージ本体であるボディ部から構成されています。
○ データヘッダー部について
ヘッダ部のステータス行は、HTTPのバージョンや、リクエストに基づいて行われた処理の結果として返されたステータスコードなどの情報をもっています。ヘッダーフィールドは、リクエストとレスポンスどちらにおいても「フィールド名：値」という形式です。フィールド名について例を挙げると、リクエストでAPI実行を一意に識別できるNoを示す当行独自のX-BTMU-Seq-Noや、レスポンスでデータの種類を示すContent-Typeなどが使われています。
○ データボディ部について
HTTPレスポンスのボディ部は、大きく分けるとオペレーション情報とデータ情報からなります。具体例として、法人向けの口座APIの入出金明細照会を挙げて説明します。（APIの仕様は、画面上部の メニュー＞API ＞法人API - 口座をご参照ください）
オペレーション情報は、次明細有フラグや次明細取得キーワードなど、取得するデータを指定するパラメータのことです。一方でデータ情報は、店番・口座番号などを口座情報オブジェクト、取引日・金額などを入出金明細オブジェクトとして定義したものです。
HTTPレスポンスデータの内部構造を下の図1にまとめました。
図1. 当行のHTTPレスポンスデータの内部構造（正常応答時）
（ⅳ）エラー情報について
ヘッダ部のHTTPステータスコードは、API利用事業者がレスポンスデータを受け取ったときの1次判断基準となるため、200が正常応答、400がクライアント起因エラー、500がサーバ起因エラーなど一般的なHTTPステータスコードの定義に従って設計しています。
口座が存在しない場合など、HTTPステータスコードでは表現しきれない詳細なエラー内容については、エラーレスポンスオブジェクトを定義し、ボディ部にてエラーコードやエラー文言を返却しています。
またHTTPステータスコードが200で送信が成功しても、業務エラーとなる場合もあります。例として、法人APIの総合振込や給与賞与振込の受付明細照会では、その特徴上、申請・承認してから実際に振り込まれるまでに時間が開く場合があり、その間に店舗統廃合などで支店番号が変更となった場合は明細の振込が実行できなくなることが挙げられます。
エラーが発生した場合でも、HTTPステータスコードとエラー情報から、API利用事業者がエラー内容に応じて実装しやすいよう設計しました。
図2. 当行のHTTPレスポンスデータの内部構造（エラー応答時）
今回はAPI設計の中でも、レスポンスデータ設計について紹介しました。当行APIのレスポンスデータは、画面上部のメニュー＞ APIから気になるAPIを選択し参照することができます。
みなさんもぜひ実際に使ってみてください！