こんにちは！kossyです！
さて、今回はキャッシュレス推進協議会のAPI開発原則が
普段のAPI設計にも活かせると思ったので、ブログにて紹介できればと思います。
本記事は
https://www.paymentsjapan.or.jp/wordpress/wp-content/uploads/2019/11/API_Guideline_Ver2.0.pdf
を全面的に参考にさせていただきました。この場を借りてお礼を申し上げます。
【原則１】API 接続先目線を意識した分かりやすくシンプルな設計・記述とすること
・オープン API は、API 接続先による利用を前提とするものであり、API 接続先目線を意識したわかりやすくシンプルな設計・記述とすることが求められる。かかる設計・記述は、API 接続先側でのバグの発生リスクの抑制や複数決済事業者と接続するFinTech サービスにおける決済事業者間の仕様差異の調整の容易化、決済事業者が他の事業者等と連携する際の API の汎用性、拡張性の確保にも資する。
・決済事業者における設計・記述に当たっては、API 接続を行うことを検討しているFinTech 企業等ともよく協議・連携することが望ましい。また、API の仕様決定後は、API 接続先が関係する部分の仕様について自社特有の用語や決済業界特有の略語等を使用しない平易な解説書（仕様書）を準備する等によって、API の仕様に対する API接続先の誤解・誤認等を防止することが推奨される。
・シンプルな設計・記述とすることは、実際のサービスに必要な項目のみを抽出のうえ提供する等の対応を意味し、メッセージ上の項目数の削減のみを目的に種類・性質の異なる複数の項目を結合・統合する等の対応を意味しない。一般に、統合された項目を分離して API 接続先がシステムに取り込むよりも、分離された項目を API 接続先において統合する方が、API 接続先のシステム設計がシンプルかつ汎用性の高いものとなる。
シンプルさ、本当に大事ですよね。
パラメータ数十個も送ったりするようなインターフェイスだとバグの元ですし、実装も煩雑になると思います。
「また、API の仕様決定後は、API 接続先が関係する部分の仕様について
自社特有の用語や決済業界特有の略語等を使用しない平易な解説書（仕様書）を準備する」
も重要だと思いました。Web開発の現場だとサーバーとフロントが別チームになっていることも多く、
ある程度規模の大きい(4 ~ 5人以上)開発ならAPIドキュメントの用意は必須だと思います。
【原則２】API の種類に応じた適切なセキュリティレベルを確保すること
・決済サービスの API（以下、「決済 API」）では、決済事業者の保有する秘匿性の高い情報が提供されるため、API の種類に応じた適切なセキュリティレベルを確保することが必要である。認証方式、通信方式等を含めた、具体的なセキュリティ対策やその水準については、「3 セキュリティ対策および利用者保護対策」を参照のこと。
・セキュリティレベルを確保する上では、提供する各 API のスコープ（機能）を適切な粒度とし、API 接続先が認可された権限以上の API を使用することができないようにすることが必要である。
・サイバー攻撃やサイバー犯罪の手口は年々巧妙化しているため、API のセキュリティ対策および水準は、API 接続先とも連携のうえ、継続的な改善・見直し、高度化を図っていくことが必要である。
・API の仕様書を一般に公開する場合、セキュリティに及ぼす影響について留意することが必要である。
認証と認可、非常に重要ですね。
「認証は本人性を証明すること」
「認可は行為の権利を認めること」
この点を履き違えていると重大なセキュリティ事故に繋がってしまいます。
必ず理解しておくようにしましょう。
ちなみにRailsでは「認証」の仕組みを提供するGemとして「devise」が有名で、
「認可」の仕組みを提供するGemは「cancancan」や「pundit」が有名です。
【原則３】デファクトスタンダードや諸外国の API 標準、国際標準規格との整合性を意識すること
・参照可能な国際標準規格等が存在する場合は可能な限り使用することが推奨される。例えば、日付や時刻の表現形式には RFC3339 や ISO8601/JISX0301、通貨コードの表現形式には ISO4217 といった標準がある。
・アーキテクチャ・スタイルやデータ表現形式、認可プロトコル等の仕様については、デファクトスタンダードや諸外国の API 標準、国際標準規格等との整合性を踏まえ、「2.3 開発標準」において推奨される基本的な仕様を定めている。
国際標準規格に従うことは地味に大事ですね、、、
規格に従わないでそれぞれが独自に開発を進めてしまうと、条件分岐が多くなったりしますので。
USBにもType-cのように規格が、電源プラグにも100ボルト2極タイプのような規格がありますが、
この規格が存在しなかった場合、各社がそれぞれ独自規格で製品を作ることによって、
互換性が無くなったり、規格がたくさん存在することで次の製品の規格をどうするか、といった余計な意思決定コストがかかること、
また消費者や開発者が困ってしまうので、プログラミングでも製品開発でも規格に従うのは非常に重要だと考えます。
【原則４】仕様変更による API 接続先への影響をコントロールすること
・API の仕様変更は、API 接続先でもプログラム変更等の影響が生じることから、影響を適切にコントロールすることが必要である。決済 API は、利用者の購買行動や資産管理行動の一部として機能する可能性があるため、仕様変更によって API 接続先が突然接続不能となった場合、API 接続先のサービスを利用する多くの利用者に影響・混乱が生じるおそれがある。
・仕様変更による API 接続先への影響を抑制するため、決済 API は、予めできるだけ汎用性、拡張性の高い設計とし、また、仕様変更が発生する可能性（機能追加、停止、バグ修正、データ形式の変更等）をできるだけ予め考慮した設計とすることが望ましい。これらは、各決済事業者における API の仕様変更コストを低減することにも資する。
・一方的な仕様変更によって API 接続先に混乱が生じないよう、仕様変更に当たっては、原則として十分な余裕をもって事前のアナウンスを行うことが必要である。また、新バージョン移行後も新旧バージョンを一定期間並行稼働させる、旧仕様を包含した新バージョンをリリースする等の対応も推奨される。
・パートナー型のオープン API の場合、通常、決済事業者側から API 接続先を特定することが可能であるため、事前アナウンス等は比較的容易であるが、公開情報等をパブリック型のオープン API を通じて提供する場合等では、決済事業者側から API 接続先を特定することができない場合がある。また、パートナー型のオープン API であっても、決済事業者への通知なく API の連鎖5を許容している場合は、仕様変更の影響範囲を決済事業者側で十分把握することができない場合がある。このため、仕様変更に当たっては、影響範囲を十分慎重に見極めた上で進めることが重要である。
- 推奨される具体的なバージョン管理の方法については、「2.3 開発標準」において定めている。
APIのバージョニング、悩ましい問題ですよね、、、
namespaceで区切る設計(api/v1/ みたいな)やホスト名にAPIバージョンを含むパターンがありますが、
一長一短だと思います。
【原則５】サービス提供までに十分な確認を行うこと
・仕様書に十分な記載が行われていたとしても、システムを稼動させることで発覚する課題等があることも想定される。そのため、実際にサービス提供を開始するまでに、決済事業者、API 接続先の双方が参加する事前の確認を十分に行う必要がある。
・上記の確認を行うための環境（テスト環境やテストデータ等）については、決済事業者側にて準備されることが望ましい。
十分な確認、頭ではわかっているんですが、なかなか実践が難しいですね、、、
専門のチームを立てた方がいいと思うのですが、資金の制約、採用の困難さ等が重なって
なかなかできないチームが多いと思います。
さすが民間団体って感じの資料ですね、、、
政府主導の資料であればこのレベルの資料は作れなかったのではないでしょうか。
他にも公表物が出ていますので、興味のある方はご覧ください。
