API 設計は『使う人の体験』を決める
REST API の設計は、それを使う他の開発者（社内・社外）の生産性を大きく左右します。一貫性のある設計は学習コストを下げ、混乱した設計はバグと問い合わせを生みます。本記事では、使いやすい REST API を設計する原則を編集部の視点で整理します。APIマネタイズ戦略 もご参考に。
REST の基本原則
(1) リソース指向：名詞でエンドポイントを表現。(2) HTTP メソッドの活用：GET/POST/PUT/PATCH/DELETE。(3) ステートレス：リクエストが自己完結。(4) 統一インターフェース：一貫したパターン。(5) 適切なステータスコード：意味のある返却。Webの基礎を学ぶロードマップ もご参考に。
エンドポイントの命名
(1) 名詞・複数形：/users・/orders。(2) 階層構造：/users/{id}/orders。(3) 動詞を避ける：メソッドで表現。(4) 一貫したケース：kebab-case 等。(5) フィルタはクエリパラメータ：?status=active。命名の一貫性が API の使いやすさの基礎です。
HTTP メソッドとステータスコード
(1) GET：取得（副作用なし）。200。(2) POST：作成。201。(3) PUT/PATCH：更新（全体/部分）。200。(4) DELETE：削除。204。(5) エラー：400（不正）・401（未認証）・403（権限）・404（不在）・409（競合）・422（検証）・500（サーバー）。ステータスコードの正しい使い分けが、クライアント実装を楽にします。データベース基礎 もご参考に。
エラーレスポンスの設計
(1) 一貫した形式：code・message・details。(2) 機械可読なコード：プログラムで分岐できる。(3) 人間可読なメッセージ：デバッグ用。(4) フィールド単位のエラー：検証エラーの詳細。(5) 機密情報を漏らさない：スタックトレース等。セキュリティエンジニアへの転身ガイド もご参考に。
ページネーション・フィルタ・ソート
(1) ページネーション：offset/limit or cursor。(2) cursor ベース：大規模データに有利。(3) フィルタ：?status=active&type=premium。(4) ソート：?sort=-created_at。(5) レスポンスにメタ情報：総件数・次ページ。データアナリストの実務スキル もご参考に。
バージョニングと進化
(1) URL バージョニング：/v1/users。(2) ヘッダバージョニング：Accept ヘッダ。(3) 後方互換の維持：破壊的変更を避ける。(4) 非推奨の告知：Deprecation ヘッダ。(5) 段階的廃止：移行期間を設ける。APIマネタイズ戦略 もご参考に。
セキュリティと認証
(1) HTTPS 必須：通信の暗号化。(2) 認証：API キー・OAuth・JWT。(3) 認可：リソースへのアクセス制御。(4) レート制限：悪用と過負荷の防止。(5) 入力検証：インジェクション対策。セキュリティエンジニアへの転身ガイド もご参考に。
ドキュメントと開発者体験
(1) OpenAPI（Swagger）：仕様の標準化。(2) サンプルコード：すぐ試せる。(3) エラー一覧：対処法を明示。(4) 変更履歴：バージョン差分。(5) サンドボックス環境：テスト用。エンジニアのドキュメント技術 もご参考に。
失敗しがちなパターン
(1) 動詞をエンドポイントに：/getUser 等。(2) ステータスコードの誤用：全部 200 で返す。(3) 一貫性のないエラー形式：クライアントが困る。(4) バージョニングなし：破壊的変更で障害。(5) ドキュメント不足：使われない API。対策は、(1)名詞＋メソッド、(2)正しいコード、(3)一貫したエラー、(4)バージョニング、(5)ドキュメント整備、です。IT・Web業界の職種完全マップ もご活用ください。