APIとは、簡単に言えば、あるソフトウェアが別のソフトウェアに何かを依頼する方法です。オンラインストアが在庫システムに残数を尋ねる。会計ソフトが銀行に今日の取引データを求める。倉庫のスキャナーが基幹システムにパレットの出荷を伝える、といったことです。
こうした連携は、最初は小さく便利なものとして始まります。しかし、複数のシステムがそれに依存するようになると、ビジネス運営の根幹となります。特定のエラーの意味や、リクエストを2回送っても安全かどうかといった曖昧な点が、あらゆる場所で問題を引き起こすようになります。信頼性は、そうした細部を明確にすることから始まります。
まずは業務内容を平易な言葉で説明する
コードを書く前に、その連携が本来何のためのものかを記述します。一方のシステムがもう一方に何を求めているのか？ 実行前に満たされるべき条件は何か？ 完了をどう判断するか？ 「在庫切れ」のような通常の拒否回答と、本当の障害の違いは何か？
これにより、連携の目的が「現在のデータベース構造」ではなく「ビジネス上のタスク」に集中します。また、全員が同じ言葉を同じ意味で使っていることを確認できます。ある場所では「完了」が「出荷済み」を意味し、別の場所では「支払い済み」を意味する場合、いずれ大きなミスにつながります。
エラーメッセージを役立つものにする
リクエストが拒否された場合、メッセージは何が問題でどう対処すべきかを示すべきです。「配送日を過去の日付に設定することはできません」は有用ですが、「エラーが発生しました」は役に立ちません。
情報の欠落、存在しない記録、2人による同時変更、権限不足、システム側の障害など、問題に応じて異なる回答が必要です。また、エラーメッセージにパスワードやデータベース構造などの内部情報を漏らすべきではありません。そうした情報は、正確な原因を追跡するためのプライベートなログに記録します。
二重送信を想定した設計
よくある問題を紹介します。あるシステムが注文を送り、受け手側がそれを保存したものの、返信が途中で消えてしまった場合です。送り手は成功したかどうかわからないため、再送します。その結果、2つの注文が作成されてしまいます。
解決策は、各リクエストに固有の参照番号を付与することです。これにより、受け手側は「これは受信済みです」と判断し、単に元の結果を返すことができます。注文、支払い、出荷を作成する処理において、これは不可欠な要素です。
大規模なレポート作成や大量のデータ処理など、時間がかかる処理もあります。その場合、システムは「受け付けました。この番号で状況を確認してください」と即座に返答すべきです。送り手に、長い沈黙が成功を意味するのか失敗を意味するのかを推測させてはいけません。
慎重な変更管理
他のシステムが連携に依存している場合、その変更はゲームの途中でルールを変えるようなものです。情報の削除がリスクであることは明らかですが、情報の「意味」をこっそり変えてしまうことも同様に危険であり、発見はさらに困難です。
変更が必要な場合は、可能な限り旧バージョンと並行して新バージョンを追加し、廃止前に十分な猶予期間を設けて周知します。そして、旧バージョンを停止する前に、まだ利用しているユーザーがいないかを確認します。
稼働後のメンテナンス
開発者のラップトップで動くだけでは完成とは言えません。実運用では以下の要素も必要です。
- 誰がアクセスしているか、何を見る権限があるかの確認
- 1つの不具合のあるシステムが全体を圧迫しないよう、送信量を制限する
- 通信中の情報の暗号化
- 遅延やエラーを早期発見するためのモニタリング
- 接続する人が迷わないよう、明確なサンプルコードを用意する
優れた連携の基準はシンプルです。それを利用するシステムが信頼でき、管理する人がその動作を理解できることです。
要約
信頼できる連携は、正しい処理を容易にし、問題を理解しやすくします。明確な合意、重複への安全な対応、慎重な変更、適切な監視。これらは後から付け加えるものではなく、正しく構築するための不可欠な要素です。