エンジニアHubproduced by エン

若手Webエンジニアのための情報メディア

API開発の基本 - 銀行APIの開発事例に学ぶ「使いやすい」のデザインプロセス

APIは多くのWebシステムにおいて、欠かすことのできない技術です。APIをどのように設計、デザインすれば、ユーザに利便性を提供できるのかを、GMOあおぞらネット銀行 CTOの矢上聡洋さんが解説します。API設計の基本、そして実際の銀行APIの設計から、“使いやすい”を生み出すためのデザインプロセスを学びます。

API設計メインカット みなさん、こんにちは。GMOあおぞらネット銀行 CTOの矢上聡洋(やがみ・あきひろ/ @akihiro_ygです。本稿では、いま世の中のWebシステムにおいて欠かせない技術の1つであるAPIについて、概論と基本をご紹介します。

さらに、その中でもこれまで閉じた世界のイメージが強かった銀行業界において、ユニークだと言われる当社の銀行APIへの取り組みと、その先にある未来についてお伝えしたいと思います。

そもそもAPIとは何か?

IT業界で、API(Application Programming Interface)という言葉よく耳にします。それ自体の説明はこちらの記事がよくまとまっていますが、ごく簡単に表現すれば、APIとはアプリケーションとプログラムをつなぐ部品(インターフェース)です。たとえば、ある家計簿アプリにおいて、ボタンを押すと銀行預金の残高をスマホ上に表示する機能を実現しようとすると、

  • (A)ボタン押す→入力内容取得→内容を元に銀行サイトにログイン
  • (B)入力内容を元に銀行勘定系データベースにアクセス→目的のデータを検索および取得
  • (C)取得した結果を整形→ユーザアプリの画面に表示

こうしたロジックが必要になります。本来的にはアプリ開発者は、Bのロジックを開発する必要がありますが、銀行側がBの部分をAPIとして公開している場合、これを利用することでBのロジックを開発する必要がなくなるのです。このようにAPIは再利用性が高く、効果的に利用することでアプリケーション開発の生産性が高まります。

「良いAPI」とはどのように設計されるべきか?

APIにはいくつかの種類がありますがWebの世界でよく使われるのがWebAPIです。WebAPIはHTTP(S)プロトコルを利用し、ネットワークを介して呼び出すAPIのことです。Facebookが公開する「グラフAPI」や、Amazonが公開する「Amazon MWS」「Product Advertising API 」などはWebAPIの好例です。

綺麗なAPIを設計するには気をつけたい5つのポイント』にまとめられているように、WebAPIを設計するうえで重要な点はいくつかありますが、APIを「公開する立場」から考えた場合、とくに忘れてはならないのは「APIは多くのユーザに使われるべき存在であること」、そのために「ユーザである開発者が使いやすいAPIでなければならない」という点でしょう。そして、本稿執筆時点においては、下記3点が「使いやすさ」を生み出すうえで重要だと筆者は考えます。

  1. REST(Representational State Transfer)の設計原則に合わせること
  2. 対象リソースとアクションとを分かりやすくすること
  3. RESTの弱点である自由度を補うSwaggerなどを公開すること

以降、各項目を簡単に解説してみます。

RESTの設計原則に合わせること

RESTは2000年に提唱されたWebシステムの設計原則で、以下の4点が定められています。

・明示的に HTTP メソッドを使う
・ステートレスにする
・ディレクトリ構造に似たURIを公開する
・XML、JSON(JavaScript Object Notation)のいずれか、またはその両方を転送する

IBM Developer『RESTful Web サービスの基本』より引用

では、なぜAPI設計においてこうした原則を踏襲する必要があるのでしょうか。それは、公開APIについて開発者視点で考えた場合、独自設計されたものよりも、「世の中に流通している標準等に則っている」ものの方が学習コストが低くなり、使いやすいからです。REST以外の標準、設計原則には過去にはSOAP(Simple Object Access Protocol )や、最近ではgRPC(g Remote Procedure Calls)などがありますが、本稿執筆時点ではRESTが広く浸透しており、そのため多くのAPI設計に活用されていると考えます。

対象リソースとアクションとをわかりやすくすること

RESTでは「明示的にHTTPメソッドを使う」とありますが、ここで重要なのはHTTPメソッドを正しく使い、APIを呼び出す対象となるリソースと、APIのアクションに一貫性を持たせることです。

たとえば、銀行口座に対して操作を実施するAPIの場合、以下のようなアクションが想定されます。

  • 口座一覧照会、残高照会:GETメソッドを利用(GET /balance)
  • 振込依頼:POSTメソッドを利用(POST /request)

照会系APIはリソース(口座情報や残高データ)の取得であるためGETを利用、振込についてはリソース(振込データ)の新規作成であるためPOSTを利用といった具合です。HTTPメソッドを正しく使うことで、開発者のAPIに対する期待値とAPIの内容が一致する使いやすいAPIとなります。

RESTの弱点である自由度を補うSwaggerなどを公開すること

RESTはあくまで設計原則であり、プロトコルではありません。それゆえ、設計の自由度は高くなりますが、反面、実装は開発者ごとに少しずつ、異なり統一性がありません。そのため、RESTを参照して開発したAPI(RESTful API)を公開する際は、そのAPIに即したSwagger(RESTful APIを構築するためのオープンソースのフレームワーク。OpenAPIとも言われる)などのSDK(Software Development Kit:開発キット)を合わせて公開することが、開発のしやすさの観点から極めて重要となります。

また、その他の観点では、APIをバージョンアップした際に後方互換性を持たせる、1つのリクエストで自由度を持たせすぎない(対象リソースとアクションの関係が崩れるため)なども良いAPIを設計するためのポイントと考えます。

以上、2020年8月の本稿執筆時点におけるAPIの概念、また、具体的な基礎技術と特徴について紹介しました。続いて、APIの具体的なユースケースのひとつとして、銀行業界特有のAPIに関して解説します。

銀行業界でのAPIの位置付け

銀行においてもWebAPI(以降、API)を活用する動きが加速しています。銀行が自社システムの機能やデータにアクセスできるようにするAPIを「銀行API」と呼びますが、これが公開されることで、銀行の保有するデータやサービスと外部の事業者との連携が促進され、新しい価値やビジネスの創出が期待されているのです。こうした潮流は「オープンバンキング」と呼ばれ、とくに英国での注目度は高く、さまざまな面で先行しています*1

日本では2017年5月に銀行法が改正され、施行後、2年以内に銀行API公開することが努力義務となりました。また、2020年4月21日に公正取引委員会により、フィンテックを活用した金融サービスの向上に向けた競争政策上の課題についての報告書が出され、日本でもオープンバンキングの動きが加速してゆくことが予想されます*2

日本の銀行で“あるべき”APIが開発しにくい理由

先に良いAPIを開発するには標準化されていることが重要であると書きました。これは銀行APIでも、もちろん同じで、オープンバンキングが先行する英国などではOBIE(Open Banking Implementation Entity:オープンバンキング制度の推進主体)が、OpenID Foundationによる標準を採用し、これに基づくAPI仕様を策定しています。しかし、2020年7月時点の日本においては銀行APIに関する標準規格は存在せず、各銀行、手探りの状況で銀行APIを開発し、公開されているのが実状です。銀行APIに接続するサービスを運営する企業からみれば、銀行ごとに異なる仕様のAPIを実装せざるを得ない、非常に使い勝手が悪い状況だと言えるでしょう。

日本の銀行業界が変革の途上にあるがゆえ、こうした状況にあると考えられます。しかし今後、(断言はできませんが)各行の取り組みとともに、銀行業務のデジタル化、いわゆるデジタルトランスフォーメーション(DX)が進み、横断的な動きが活発化することで、今後、銀行APIの標準化に何らかの変化が見えてくるのではないかと期待しています。

GMOあおぞらネット銀行でのAPI開発の舞台裏

私が所属するGMOあおぞらネット銀行では、2018年から銀行API開発に着手し、2019年1月に参照系APIを、同年5月に更新系APIを公開しました。開発にあたり考慮した点や、できあがったAPIの特徴など、その舞台裏について少しお話します。

「使いやすいAPI」を実現するためのコンセプト

我々の銀行APIは電子決済等代行業者だけでなく、その他の一般企業も利用するケースを想定して開発を進めました。そのためAPI連携に不慣れな開発者にも分かりやすいドキュメントを整備し、SDKなども無料公開しています。また、API接続企業のみなさまのシステム負荷を軽減するため、イベント発生を銀行側から通知するWebhook機能を提供するなど、API接続企業の開発者の方々にとって開発しやすい環境や機能も充足させています。また、以下のような点も重要なコンセプトとして考慮しています。

■API公開基盤

当社独自の公開基盤ではなく、外部の公開基盤サービスを利用しAPIフォーマットなどを変更できるようにしました。これは将来、国内で銀行APIの標準化が進んだ際に、仕様改修の最小限に抑えられることを期待しての判断です。

■セキュリティ

非金融業界の公開APIと比較し、銀行APIは求められるセキュリティレベルが格段に高いです。そのため、後述するOAuthやOpen ID Connectの採用に始まり、多要素認証やリスクレベル認証(アクセスしてくる環境、タイミングなどにより認証方法を変更する認証方式)をアプリケーションフローに取り入れ、単発の銀行API呼び出しでなく、複数の銀行APIを組み合わせてセキュリティを高めるアーキテクチャとしています。

使いやすい銀行APIをいかに実装するか

2018年に我々が銀行APIの開発検討に入った当初、国内で先行する事例はほとんどなく、なにから手を付ければいいのかもわからない状態でした。そのため欧州やアジア各国の先行事例、また国内では金融システム開発会社が公開している資料などを参照し、実装の方向性を検討していったのです。結果として、さまざまな要素が組み合わさったハイブリッドな仕様といえるものになりました。

ユーザが使いやすい仕様を目指す

国内銀行におけるAPI標準規格は存在しないものの、APIの設計については、前述のRESTの設計原則を参照できます。我々のAPIもRESTの「リソースとアクションの関係をわかりやすく」に準拠し、参照系APIはGETメソッド、更新系APIはPOSTメソッドのように、アクションと分類を紐付けています。具体的には、以下のように整理できます。

メソッド アクション
GET 振込状況照会、振込依頼結果照会
POST 振込依頼、振込取消依頼

また、その他には、なるべくページ送りをさせない、という工夫も盛り込んでいます。たとえば、入出金明細など、レスポンスのデータ量が多くなると見込まれるAPIについてはあらかじめレスポンスの上限値を500で定義しておき、それ以上明細が必要な場合は1回目のレスポンスにセットし、次の明細ページのアクセスキーをセットして再度APIを呼び出す仕様にしています。これにより不用意にシステム間のトラフィックが増大することを防止しているのです。

ページ送りの仕組み
明細のレスポンス内容例

▲明細のレスポンス内容例。nextItemKeyが次ページへのアクセスキーになる

さらに、ユーザの開発負荷を軽減させるべく、イベント通知のWebhook APIを開発しています。たとえば請求書送付先企業から、振込入金口座に入金が入ったことを確認して何かのタスクを起動したい場合、通常は接続先企業から常に入金口座に入金情報を照会し、入金状況を確認する必要があります。

こうしたデザインでは、開発時、実運用時、いずれの局面においても開発者とシステムに負荷がかかります。そこで、入金されたイベントをトリガーとして通知するAPIを開発し、ユーザを「入金口座を常に確認する」という状況から解放しています。

Webhook APIの利用イメージ

▲Webhook APIの利用イメージ

ユーザの開発負荷を減らす意味では、SDKを6言語(Node.js、Go、Ruby、Java、PHP、Python)分、GitHubに公開していることも、こだわりのひとつです。

Node.jsの例

▲Node.jsの例

2つの認可プロトコルを採用

先述のとおり、銀行APIには高いセキュリティレベルが求められますが、我々はセキュアであることと、使いやすさの両立を目指しています。認可プロトコルについて、OAuth2.0だけでなくOpenID Connectも利用できるようにしているのはこのためです。我々がAPIの設計を検討していた当時、海外ではOpenID Foundation傘下のワーキンググループが策定を進めているFinancial-grade API(FAPI)において、認可プロトコルの標準はOpenID Connectが検討されていました。OpenID ConenctはOAuth2.0と比較してID連携部分の標準化が進んでおり、「標準化を重視する」という方針を持っていた我々には向いていたのです。

しかし、当時の国内動向はほぼOAuth2.0の採用が主流であり、これにに準拠しておかないと接続先企業のみなさまの負担になってしまう可能性があります。こうした背景から、OpenID ConenctとOAuth2.0という2種類の認可プロトコルを提供しているのです。

OpenID Connectの認可フロー

▲GMOあおぞらネット銀行が提供するOpenID Connectの認可フロー

今後の展望

銀行APIは、それ自体、まだ馴染みが薄く、また一般にはその役割りも理解しづらいため、実際の利用にあたっての心理的ハードルが存在します。開発者のみなさんができるだけハードルを感じることなく、手軽に利用できるよう当社APIを自由にテストできるサンドボックス環境、「-GMOあおぞらネット銀行API実験場-」を、2020年4月7日にリリースしました。

このサンドボックス環境を利用することで、実際に手を動かして当社APIを利用することができ、これまで興味はあったけど実際に利用するのはちょっと……、と思われていた方にも気軽に触っていただけると思います。この「sunabar」をきっかけに銀行APIから始まる金融DX実現されていくことを期待しています。

最後までお読み頂きありがとうございました。また本記事執筆にあたりアドバイスいただきました千葉剛さんにこの場を借りて御礼申し上げます(2020年9月)。

矢上聡洋(やがみ・あきひろ) @akihiro_yg

矢上聡洋
日本アイ・ビー・エムに入社後、カードや信販系企業向けシステム開発でSE、アーキテクトなどを担当し、その後、金融系チーフアーキテクト部門責任者に。その後、2019年にGMOあおぞらネット銀行にジョインし、CTOとして同社の技術評価やアーキテクチャデザインを行う。

関連記事

編集:馮富久(株式会社技術評論社

*1:2020年4月24日 銀行APIの可能性を探る ~sunabar-GMOあおぞらネット銀行API実験場- 始動~セミナー Head of FINOLAB 柴田誠氏 講演資料より

*2:詳細は『(令和2年4月21日)フィンテックを活用した金融サービスの向上に向けた競争政策上の課題について』に詳しい。