本番品質のREST API構築：実践チェックリスト

呼び出す人のために設計する

良いAPIは予測可能です。リソースには名詞を使い、標準的なHTTPメソッドとステータスコード、一貫した命名、単一のエラー形式を採用します。ひとつのエンドポイントを理解した開発者が、次のエンドポイントの動きを推測できるべきです。

• リソース名と複数形の一貫性。
• すべての一覧エンドポイントにページング、絞り込み、並べ替え。
• コード、メッセージ、詳細を持つ標準のエラー形式。
• 決済や注文を作成する操作には冪等キー。

すべてのリクエストにセキュリティを

すべての呼び出しを認証し（通常はOAuth 2.0や署名付きトークン）、すべての操作を呼び出し元のロールとスコープに照らして認可します。入口で入力を検証し、リクエストサイズを制限し、クライアントごとにレート制限をかけて、ひとつの連携がサービスを使い果たさないようにします。

利用者を壊さないバージョニング

新しいフィールドやエンドポイントの追加は、誰も壊さないはずです。フィールドの削除や名前の変更は壊します。APIを明示的にバージョン管理し、廃止は早めに告知し、利用者が移行するまで古いバージョンを動かし続けましょう。

ドキュメントと開発者体験

コードから生成したOpenAPI仕様は、ドキュメントを正確に保ちます。リクエストとレスポンスの例、認証の手順、そして連携先が安全に試せるサンドボックス環境を加えましょう。

プロダクトとして運用する

長く使われるAPIは、どう使われているかを把握し、問題があればすぐに気づけるオーナーがいるAPIです。

• エンドポイントごと、クライアントごとにレイテンシとエラー率を追跡する。
• 問題をエンドツーエンドで追えるようリクエストIDを記録する。
• イベント通知には再送と署名付きのWebhookを使う。
• 利用者向けにステータスと変更履歴を公開する。