【ITニュース解説】How to Design Quality APIs

API設計で重要なのは、明確さと柔軟性のバランスを取ることだ。良いAPIは退屈であるべきで、API利用者がAPI自体ではなく、本来のタスクに集中できるようにする必要がある。しかし、APIは一度公開すると変更が難しく、変更は既存の利用者のシステムに影響を与える可能性がある。

APIに変更を加える場合、レスポンスに新しいフィールドを追加するなどの追加的な変更は比較的安全だが、既存のフィールドを削除したり、データ型を変更したり、構造を変更したりすると、依存するコードが破損する。APIを維持する上で重要な原則は「ユーザー空間を破壊しない」ことだ。やむを得ずAPIの変更が必要な場合は、バージョン管理を導入し、新旧両方のバージョンを同時にサポートすることが望ましい。これにより、既存の利用者は古いバージョンを継続して使用でき、新しい利用者は新しいバージョンを選択できる。ただし、APIのバージョン管理は利用者を混乱させ、保守担当者の負担を増大させる可能性があるため、可能な限り避けるべきだ。

API自体の出来栄えよりも、それが提供する製品やサービスの価値が重要だ。魅力的な製品であれば、多少APIの設計が悪くても利用者は集まる。ただし、APIがないと、技術的な利用者はAPIによる連携を求めるだろう。技術的に貧弱な製品では、優れたAPIを構築することは難しい。なぜなら、API設計は通常、製品の主要なリソースに基づいているからだ。

APIの利用開始を容易にするために、長期間有効なAPIキーによる認証をサポートすることが望ましい。APIを利用するユーザーは、必ずしも専門の開発者ではなく、プログラミングの知識が少ない人も含まれるからだ。

APIリクエストが失敗した場合の対策として、べき等性（同じリクエストを何度繰り返しても結果が変わらない性質）を考慮する必要がある。特に、決済など重要な操作を行うAPIでは、リクエストにべき等キーを含めることで、リトライによる重複処理を防ぐことができる。

APIはUIよりも高速に大量のリクエストを処理できるため、悪意のある利用や不注意な利用によってシステムに過負荷がかかる可能性がある。そのため、APIリクエストにはレート制限を設け、必要に応じてAPIを一時的に停止できる機能を設けることが重要だ。

大量のレコードを扱うAPIでは、ページネーションが必須となる。単純なオフセットベースのページネーションは、レコード数が増加するとパフォーマンスが低下するため、カーソルベースのページネーションを使用することが推奨される。カーソルベースでは、オフセットの代わりにカーソル（通常は最後のレコードのID）を使用し、データベースがインデックスを使用して効率的に次のページを取得できる。

APIレスポンスの一部が処理にコストがかかる場合、それらをオプションフィールドとして、必要な場合のみリクエストパラメータで指定できるようにすると良い。

これまでの議論は主に公開APIに関するものだが、社内でのみ使用される内部APIにも、ある程度適用できる。内部APIの利用者は通常、専門の開発者であり、変更の影響範囲も限定的であるため、公開APIほど厳格な制約はない。しかし、内部APIもインシデントの原因となる可能性があり、主要な操作についてはべき等性を考慮する必要がある。