APIの設計思想について

１． 当行APIで提供しているサービスの粒度（単位）

当行のAPIは、インターネットバンキング（三菱UFJダイレクト、BizSTATION）で提供している複数のサービスから選んだ一部のサービスをAPIとして提供しています。
各APIでは、例えば「口座API」の場合、お客さまの残高照会、入出金明細照会などを取得することができます。インターネットバンキングで提供しているサービスを踏まえたAPIの粒度となっています。

２． APIの設計方法とURI（エンドポイント）の考え方

（１） APIの設計方法

APIの設計にあたり、使い勝手を重視しRESTfulでシンプルな設計を行うという方針のもと、開発を行いました。APIの設計では、オブジェクト指向の考え方を採用しており、API化するサービスをクラス、プロパティ（フィールド）、メソッドに落とし込んで、設計を進めました。例えば、残高照会や入出金明細照会を行う口座APIの場合、「口座」というクラスに対して、「残高情報」、「入出金明細情報」といったプロパティが存在します。これらの情報（プロパティ）を取得するために、HTTPメソッドのGET/POSTを使用して、APIを呼び出すシンプルな設計としました。
また、API数を不必要に増やさないために、1つのAPI（＝リソース）に対し、複数のオペレーションが含まれる作りとしています。例えば、法人APIの一つである「口座API」には「口座残高照会」、「入出金明細照会」、「振込入金明細照会」の3つのオペレーションが含まれます。

（２） URI（エンドポイント）の考え方

APIのリクエスト先であるURI（エンドポイント）には、APIのバージョン、API名称、リクエストパラメータなどが含まれています。URIをHTTP（GET/POST）で呼び出すことで、APIの応答を実現しています。上記のオブジェクト指向の考え方を踏まえた、URIとしています。 URIの構造など、くわしくはAPI仕様を当開発者ポータルに記載しています。（画面上部の メニュー＞API をクリック）

３． 開発で工夫した点

当行APIの特徴は前述したとおりですが、ここでは実際のシステム開発時における工夫した点を紹介します。
プロジェクトの初期段階では、検討中のAPIが実際に使えるものなのか不明確だったため、ベータ版として当行APIの利用が見込まれる事業者の皆さまに仕様やテスト環境を提供し、フィードバックを頂くプロセスを経て、最終的に公開するAPIのURIやオブジェクトの設計を進めました。
例えば、「入出金情報は履歴のサイズ（明細数）が大きくなるため、工夫が必要ではないか」という声を受け、1件のリクエストに対して、履歴件数の上限を設けることにしました。一定の履歴件数を超える場合は、「次の明細開始番号」を返却し、次のAPIリクエスト時に開始番号を指定する設計としました。その他にも、テストデータやエラーレスポンスに関するご要望に対する取り込みも行っています。
また、2017年7月に全国銀行協会にて纏められた「オープンAPIのあり方に関する検討会報告書」の仕様標準にも準拠する形としています。