外部インターフェース一覧を作ろう

ライフマップ開発チームの富山です。
webサービスを開発するにあたり、仕様書や運用ドキュメントなどは大事ですよね。今回は、その中でもあまり日の当たらない「外部インターフェース一覧」について、「なぜ必要なの？」「どう書くの？」という点を押さえながら書いていきたいと思います。

そもそも「外部インターフェース」って何？

簡単に言うと「あるプログラムが他のプログラムとデータをやり取りする機能」のことです。※interfaceとは「接点」「境界面」という意。
わざわざ「外部」とつけるのは、ユーザーインターフェースなど他のインターフェースと区別するためのようです。
そして「どこと連携しているのか」「データ形式は何か」などを一覧にしてまとめたのが「外部インターフェース一覧」になります。
「ソースコード読めば分かるでしょ」と思っている方も今一度ぜひ。

なぜ必要なの？

私が思いつくメリットを以下に挙げます。
「ソースコード読めばわかるでしょ」という方にとってもメリットはあります（たぶん）

・あるプログラムが他のプログラムに影響しているのか一目瞭然
あるプログラムに対して機能追加や改修を行う時に、影響範囲やデータ形式などが分かっている方が実装しやすいですよね。

・バグや障害が発生した時に影響範囲や原因特定がしやすい
開発環境ならまだしも、本番で障害発生したら早急に復旧したいですよね。焦っている時ほど抜け漏れが発生しますし、一覧でまとまっていれば、少なくとも記述されている分はすぐに調査できます。

・脱属人化！
開発した人だけが理解しているということになると、後々、他の人がメンテナンスしたりするのが大変になってしまうことも…。
また、引き継ぎの際にも資料としてあった方が良いですよね。
（明日の自分は赤の他人とも言うくらいです。１年後に同じコードを見た時にgood jobと褒めている自分自身を想像しましょう）

・非エンジニアに説明しやすい
サービスを説明する際や企画など話し合う時に、現状の構成がどうなっているのか説明を求められたりします。
その際に一覧があると非エンジニアの皆さんにも分かりやすいですよね。
例えば外部の有料APIを使用している場合、「外部の有料サービスを使っていて、ここに影響しています」というのを示しやすいと思います。
※システム関連図もあると尚良し。

どう書くの？

書き方の絶対的なルールは存在せず、それぞれのプロジェクトで必要だと思われる項目を好きな形式で書いてOKのようです。
以下に販売管理システムを参考例として、最低限これだけはという項目を挙げておきます。

エクセルで書くとこんな感じ

おすすめ参考資料

IPA（情報処理推進機構）が良い感じに資料をまとめてくれていますので、古い内容ですが参考になると思います。
元は「機能要件の合意形成技法」という資料の一部です。内容が濃すぎるので分冊化されており、その中の「分冊５ 外部インタフェース編」というのが今回ご紹介したい内容です。
この資料がとても勉強になりますのでぜひ外部インタフェース編以外も読んでみてください。

エンタプライズ系事業/機能要件の合意形成技法 | アーカイブ | IPA 独立行政法人 情報処理推進機構

終わりに

こういうドキュメント系はあった方が良いと分かってはいるものの、忙しいと疎かにしがちですし、あっという間に陳腐化するのもザラですよね。日々の業務負担と引き継ぎ・外部への説明時の手間を天秤にかけた時、やはり目の前の業務で負担増やす方が面倒に感じますしね…。
それでも、これが自分自身と他メンバーへの貢献になると信じて必要十分な内容の資料作成を怠らず地道にやっていきたいと思います。