REST API（Representational State Transfer）は2000年、Roy Fieldingが博士論文で提唱したアーキテクチャスタイルに基づくWeb APIの作り方です。「HTTPメソッド（GET/POST/PUT/DELETE）」と「リソースを表すURL」を組み合わせて、シンプルかつスケーラブルにAPIを設計できるスタイルとして、2010年代以降のWeb API設計のデファクトになりました。厳密にはRESTには制約が多数ありますが、現代では「リソース指向＋HTTPメソッドで操作するAPI」を広くREST APIと呼ぶ慣習が定着しています。
この記事の目次
- RESTの基本ルール
- HTTPステータスコードの基本
- REST設計のベストプラクティス
- RESTとGraphQL/gRPCの使い分け
- まとめ
RESTの基本ルール
RESTは「URLで対象（リソース）を表し、HTTPメソッドで操作を表す」のが基本。例えば GET /users でユーザ一覧、POST /users で新規作成、PUT /users/123 で更新、DELETE /users/123 で削除、というように、メソッドが「動詞」、URLが「名詞」を担います。
ステートレス（state-less）も重要原則で、サーバはリクエストごとに独立して処理し、前のリクエストの状態に依存しません。認証情報も毎回トークン等で送る前提なので、スケーラブルで分散しやすい構造になります。
HTTPステータスコードの基本
REST APIはHTTPステータスコードを意味通りに使うことが重要です。成功は2xx、リダイレクトは3xx、クライアントエラーは4xx、サーバエラーは5xx。「すべて200を返してbody内でerror: trueを表現する」は古い悪習で、現代のREST設計ではタブー視されます。
認可エラーは401（認証必要）と403（権限不足）を使い分け、リソースが見つからない場合は404、バリデーションエラーは422（Unprocessable Entity）といった具合に、HTTPの語彙をフルに使うのが王道です。
REST設計のベストプラクティス
実務でのREST設計には定番のベストプラクティスがあります。リソース名は複数形で統一（/users であって /user ではない）、URLにはバージョン（/api/v1/users）かAcceptヘッダで管理、一覧取得には ?page=2&per_page=20 のようなページネーション、レスポンスのエラー形式（フィールド名と意味）を仕様書で明示。
ドキュメント化にはOpenAPI（Swagger）が事実上の標準で、YAML / JSON でAPI仕様を書けば、サンプルリクエスト・SDK生成・テスト自動化まで連動します。「APIファースト開発」と呼ばれる進め方が、現代Webバックエンドの主流です。
RESTとGraphQL/gRPCの使い分け
REST一強ではなく、用途に応じてGraphQLやgRPCも選ばれます。GraphQLは「クライアントが欲しいフィールドだけ取れる」柔軟性が強みで、モバイルアプリや複雑なUI向けに人気。gRPCはProtocol Buffersベースの高速バイナリ通信で、マイクロサービス間連携に向きます。
とはいえ「公開APIならRESTが最も一般的でキャッシュも効きやすい」というのは現代も変わらず。「公開はREST、社内マイクロサービスはgRPC、モバイルアプリのAPIはGraphQL」のように使い分ける構成がよく見られます。
まとめ
REST APIはWeb APIの基本にして決定版で、エンジニアなら一通りの設計ができるべき必須スキルです。厳密なREST制約に固執しすぎず、実用面でのベストプラクティスを身につけることが現代のAPI開発の王道です。
※本記事はIT用語辞典の手書きドラフトです。公開前に最新情報・出典を確認のうえ加筆修正してください。
コメント