こんにちは。メルペイ バックエンドソフトウェアエンジニアの id:koemu です。
今日は、外部APIと連携する機能のデータの持ち方について、振込申請のシステムを事例に取り上げていきます。
基本データ・拡張データに分ける
定義
まず、データを、「基本データ」「拡張データ」に分けます。
ここで、「基本データ」とは、提供する機能において最低限必要となる情報です。振込申請ですと以下のデータとなります。
- 名義
- 口座番号
- 申請日
- 申請受理日
- 振込完了日
- ステータス(受付完了/送金完了/送金失敗/その他)
一方、「拡張データ」とは、基本データでは網羅していない、外部APIが必要としているデータを指します。例えば、連携用のレコード別のIDや、ステータスの遷移などです。振込申請ですと次のデータになります。
- ステータス(プロセッシング事業者が持つより詳細なステータス)
- IDのマップ(基本データと拡張データの間で変換が必要な場合)
- 状態が変わった時刻
基本データについて
基本データの定義を再掲すると、「提供する機能において最低限必要となる情報」になります。また、これは外部APIに依存しない情報でもあります。したがって、業務を分析した上でどのようなケースでも必要性が高いデータがここに残っていると考えて良いでしょう。特に、ステータスについては、抽象度の高い、かつ業務が表現しきれるシンプルなステータスで管理できるようにします。
慣れていない中でも、実際に取り組む場合は、いくつかかケースを想定しながら組み上げるとよいかと思います。
拡張データについて
拡張データは、基本データでは表現しきれないデータを保存します。例えば、振込申請の場合、利用するプロセッシング事業者で違いがあります。そのため、基本データで網羅できない詳細な情報を記録します。
また、外部APIの通信先となっているプロセッシング事業者が切り替わったり、プロセッシング事業者の中でもAPIの体系が変わることで保存しなければならない情報が変わってくる可能性があるため、その変更のしわ寄せを拡張データの部分で吸収するという意味合いもあります。
例えば、ステータスは、プロセッシング事業者により、金融機関との通信状態を詳細に返す仕様が存在する場合があります。しかし、提供する機能としては直接必要としない、かつプロセッシング事業者によりその状態遷移が変わってくるものがあるため、基本データにはその詳細は保存せず、拡張データに詳細に保存します。
なぜ基本データと拡張データに分けるのか
基本データと拡張データに分ける最大の理由は、外部APIを利用しているとその外部APIの利用先が変わる可能性があるからです。
外部APIの接続先が変わったとき、データの設計がそのAPIと密な状態、すなわち基本データと拡張データが別れていない状態となっていると、システムの大幅なリファクタリングが必要となります。そうなりますと、APIの切替の妨げとなったり、場合によってはシステムを停止させなければならないこともあります。
このような事態を避けるために、事前に分けることが重要です。
図示すると
これまでの説明を図示すると以下の通りになります。
参考資料
以前、別の勉強会で似た話題で発表をしたことがあります。合わせてご覧ください。
まとめ
外部APIと連携している機能については、データを外部APIに依存しない「基本データ」と、外部APIと密に連携する「拡張データ」に分けて保存しましょう、というお話でした。
それでは皆様、ごきげんよう。
