【その7】基本設計書 ④API
今から 4 年以上前に MBO に書いてしまった、新人ちゃん向けのメルマガが出てきた。
そろそろ終わりが見えてきた。
たぶん疲れてたんだろう、前段が短い。内容も若干薄めやし。
API は・・・あんまやりたくなかったなー。
連携元、連携先システムを同時に自社で作るんならまだしも、大抵が現行システムや他ベンダーが作る別システムやもんなー。
とにかく調整が面倒！後手に回ったら開発が大変になることが多かった。
なので、先手先手で「ウチはこうします！お客様とも了承をうけています！」ぐらいで持っていかないと、こっちの思うようにならんからね。
ウチの利益が最優先。他ベンダー？(´・ω・`)知らんがな。やるかやられるかじゃ！
※以下、当時の文章。
基本設計書シリーズの最後を飾るのが API です。
基本的な進め方はバッチと少し似ていますが、連携相手が他システム（別ベンダー）となると、コミュニケーション能力がカギとなってきます。
特に現行システムだとなかなか調整が難しいところがあるので、「何をどうしてほしいのか」をできるだけ明確にする必要があります。
API 設計とは
1）ソフトウェアインターフェース
ソフトウェアインターフェースは、プログラム間でデータや指示をやり取りする手順や形式を定めたもの。代表的なものとして、OSやミドルウェア、ライブラリなどの機能を外部から呼び出して利用するため規約であるAPI（Application Programming Interface）がある。
→ ここでは、ざっくりですが「API 設計＝インターフェース設計」とします。
API 設計で決めること
大きく分けて、以下の 2 つです。
- 基本情報（API 仕様）
- 処理の流れ
※以下、私見です！
大まかな流れはバッチ設計と似ている気がします。
API 設計の方が相手（他システム）を意識する点、通信速度を気にすることが多い点で、設計の方法が異なりますが・・・。
１. 基本情報（API 仕様）
API の基本的な仕様を決めます。
主に、API の連携方法や入出力を決めます。
＜決める必要のある内容＞
| 内容 | 概要 |
|---|---|
| 処理区分 | API がどういう処理を行うのかを記載します。 データの取得（参照）か、データの更新かを明確にします。 |
| 配置場所 | API がどこに配置されるのかを記載します。 複数システムがある場合、サーバーによって API の配置先が異なる場合、特に必要です。 |
| 要求（連携元、連携方法） | 該当する API の呼び出し元のシステム（連携元）とインプット（連携方法）を記載します。 連携方法には JSON やファイル形式（CSV、TSV 等）を記載します。 |
| 応答（連携先、連携方法） | 該当する API の呼び出し先のシステム（連携先）とアウトプット（連携方法）を記載します。 連携方法には JSON やファイル形式（CSV、TSV 等）を記載します。 |
| 連携タイミング | API が呼び出されるタイミングを記載します。 |
| 説明 | API についての説明を記載します。 |
２. 処理の流れ
API 仕様で決めたインプットとアウトプットを具体化し、処理フローを記載します。
（何をもらって、何を返せばいいのかの明確化）
＜決める必要のある内容＞
| 内容 | 概要 |
|---|---|
| 処理フロー | API の起動タイミング～処理終了までを図式化します。 |
| 処理概要 | 処理フローにある項目ごとに、処理の概要を記載します。 |
＜補足＞
処理概要をどこまで書くか？という問題がよく出てきます。
※以下、私見です！！
個人的には「詳細設計書があるなら概要のみ、詳細設計書が無いなら処理概要に詳細を書く」方が良いと思います。
API 設計のコツ
- インプット、アウトプットをしっかり固めること
API を使用する際、必ず通信相手となる別システムがあります。
通信相手が既存サービスの場合（例：Yahoo API、等）、インプット、アウトプットは明確で不可変なので、そのルールの中で設計する必要があります。
通信相手となるシステムも構築中であれば、よく認識を合わせて仕様を決める必要があります。
※できるだけこちらから仕様を提示するのがお勧めです。相手に合わせてもらう方が設計・実装ともにラクになります。
- 処理速度に留意すること
オンバッチと同じく、API も画面側から呼ばれることが多いため、処理速度には留意してください。
API は別システムとの連携になるため、相手側システムｂに負荷がかからないように設計してください。
※その逆（API が呼ばれた際に、自システムに負荷がかからないようにする）も同様です。API を呼び出す頻度にも注意してください。
