基礎知識

API連携の設計と運用。提供する側・利用する側の実務

APIは一度公開すると簡単に変えられません。この記事では、提供する側と利用する側それぞれの実務的な設計を整理します。

設計で最初に決めること

APIを提供する側になった場合、着手前に定めるべき項目があります。

誰が使うのか。社内の別システムか、取引先か、不特定多数か。公開範囲によって、求められる水準が変わります。

変更できるか。社内なら調整して変えられますが、外部に公開したものは勝手に変えられません。

粒度。細かく分けるか、まとめて返すか。細かいほど通信回数が増え、まとめるほど不要なデータも運びます。

誰が責任を持つか。障害時の連絡先、仕様変更の通知経路。

これらを決めずに実装すると、後から変更できない制約を抱えます。

版の管理

外部に公開したAPIは、勝手に変えられません。この制約への対処が版の管理です。

壊れる変更と壊れない変更を区別します。項目の追加は多くの場合安全ですが、削除や意味の変更は利用側を壊します。

版を分ける方法はいくつかあります。URLに含める形、ヘッダーで指定する形。どれを選ぶかより、一貫していることが重要です。

旧版をいつまで維持するかを決めておきます。無期限に残すと、保守の対象が増え続けます。

廃止の予告。利用者が移行する時間を確保する必要があります。

この設計を怠ると、変更できないまま古い仕様を抱え続けることになります。

誤りの扱い

実務で品質の差が出るのが、この部分です。

状態を示す番号を正しく使う。利用者の誤りか、こちら側の障害か。区別できないと、原因の切り分けができません。

本文で理由を返す。何が不正だったかを示します。ただし、内部の構造が推測できる情報は返さないのが原則です。

形式を統一する。誤りの返し方が場所によって違うと、利用側の処理が複雑になります。

一時的な失敗と恒久的な失敗を分ける。再試行すべきかどうかを、利用側が判断できるようにします。

記録を残す。いつ、誰が、何を呼び、何を返したか。問題が起きたとき、双方の切り分けに必要です。

制限と保護

公開するAPIには、保護の仕組みが要ります。

呼び出し回数の制限。特定の利用者による過剰な呼び出しが、全体に影響しないようにします。

認証と権限。誰が呼んでいるかを識別し、できる操作を制限します。

返す件数の上限。全件を返す設計は、データが増えたときに破綻します。

入力の検証。想定外の値が渡された場合の動作を定めます。

いずれも、後から追加するのが難しい要素です。利用者がいる状態で制限を加えると、既存の利用が壊れます。

利用する側の設計

外部のAPIを使う場合の要点を整理します。

相手が落ちている前提で設計する。応答がない、遅い、誤りを返す。これらの場合にどうするかを決めておきます。

再試行の設計。すぐ何度も呼び直すと、相手の負荷を増やします。間隔を空ける方法が使われます。

時間切れの設定。応答を待ち続けると、こちら側も止まります。

切り離す仕組み。相手が繰り返し失敗する場合、一時的に呼び出しを止める設計があります。

記録を残す。問題が起きたとき、こちらの問題か相手の問題かを示す根拠になります。

運用まで含めた設計

最後に、公開後の視点を整理します。

文書と実装をずらさない。古い仕様書は、ないより有害な場合があります。

利用状況を把握する。誰が、どの機能を、どれだけ使っているか。廃止の判断材料になります。

連絡経路を持つ。仕様変更や障害を伝える手段。外部公開では特に重要です。

変更は影響の大きい判断です。APIは他システムの前提になるため、修正の自由度が低くなります。

最初の設計が長く影響するという点が、この領域の本質だと考えます。

方式の選択

APIの作り方には、いくつかの流儀があります。

REST。資源を単位として、標準的な操作を組み合わせる方式。最も広く使われています。

GraphQL。必要な項目を利用側が指定する方式。通信回数を減らせますが、サーバー側の負荷管理が難しくなります。

gRPC。システム間の通信に向く方式。効率が高い一方、ブラウザからの直接利用には制約があります。

Webhook。こちらから呼ぶのではなく、相手から通知を受ける形。

選択の基準は、利用者と用途です。不特定多数が使うならREST、画面ごとに必要な情報が違うならGraphQL、内部の高頻度通信ならgRPCという整理が一般的です。

文書と開発者体験

APIの価値は、使いやすさで決まります。

文書が実装と一致していることが最低条件です。仕様から自動生成する方法が広く使われます。

試せる環境。実際に呼び出して確認できると、導入の障壁が下がります。

例を示す。よくある使い方の具体例があると、理解が速くなります。

変更履歴。いつ何が変わったかを追える状態にします。

問い合わせ先。不明点をどこに聞けばよいか。

外部に公開する場合、これらの整備が利用者数を左右します。技術的な優劣より、使いやすさが選ばれる理由になります。