API連携は、サービス同士をつなぐための入口になる。 けれど、URLとキーを用意して一度通信できた段階では、まだ機能として扱える状態ではない。 誰が何を送れるのか、返ってきた情報をどこまで信じるのか、失敗したときに何を止めるのか。 連携の境界を決めないまま処理を増やすと、便利な自動化ほど直しにくくなる。
ここでは、外部APIを使う前に分けて確認したい四つの境界を整理する。
認証の境界#
最初に確認するのは、どの主体の権限で呼び出すかである。 アプリケーション全体のキーでよいのか、利用者ごとの同意が必要なのか、読み取りと更新で権限を分けるのか。
キーやトークンは、画面に埋め込んだり、共有のドキュメントに置いたりしない。 サーバー側の安全な設定として持ち、必要な権限だけを与える。 連携先を増やす前に、失効、更新、漏えい時の止め方まで考えておくと、後からの移行が小さくなる。
データの境界#
APIの仕様には多くの項目が並ぶが、最初から全部を受け取る必要はない。 機能に必要な値だけを選び、入力と出力の形式をアプリケーション側で定義する。
たとえば外部サービスから取得した名前や状態を表示するなら、どの時点の情報か、欠けていた場合に何を見せるかを決める。 受け取ったデータをそのまま内部の形式へ広げると、相手側の変更が画面や保存データへそのまま波及する。 変換する場所を一つにまとめると、仕様変更を追いやすい。
失敗の境界#
通信には失敗がある。 時間切れ、権限切れ、連携先の一時的な停止、同じ処理の重複実行。 成功時の画面だけを作っていると、失敗したときに利用者も開発者も状況を判断できない。
処理ごとに、再試行してよい失敗、利用者へ知らせる失敗、すぐ止める失敗を分ける。 更新や課金のように同じ操作を二度実行したくない処理では、重複を防ぐ識別子や履歴も必要になる。 「失敗したらもう一度送る」と一律に扱わないことが、連携を壊さない基本になる。
実行の境界#
取得、下書き作成、送信、削除は、同じAPI呼び出しでも結果の重さが違う。 利用者の代わりに外部へ変更を加える処理は、対象と内容を確かめられる形にする。
自動実行を選ぶなら、いつ、誰の権限で、何を実行したかを記録する。 画面上で一度成功と表示されたことより、後から変更内容を追えることのほうが、運用では重要になる。
APIは、個人開発でも大きな機能を組み合わせる手段になる。 だからこそ、つなぐ前に境界を分ける。 認証、データ、失敗、実行の四つを確認しておけば、次の連携を足すときにも、何を守るべきかを見失いにくい。
