REST API：シンプルかつ強力なWebインターフェースの基本

はじめに

フロントエンドとバックエンドの連携、マイクロサービスの通信、外部サービスとの統合──
これらに欠かせないのが「REST API」です。
本記事では、RESTの基本原則から設計パターン、HTTPとの関係、実装時の注意点までをやさしく解説します。

基本情報・概要

REST（Representational State Transfer）は、Webの仕組みに準拠したアーキテクチャスタイルです。
REST APIはその原則に従って設計されたWeb APIであり、HTTPプロトコルを活用してリソースを操作します。

シンプルかつ直感的な設計（URI + HTTPメソッド）
ステートレスであることが原則
キャッシュやレイヤード構造なども対応可能

比較・分類・特徴の表形式まとめ

要素	説明
リソース指向設計	URLは「動詞」ではなく「名詞」で表す `/users` など
メソッドマッピング	GET＝取得、POST＝作成、PUT/PATCH＝更新、DELETE＝削除
ステートレス	サーバーはクライアントの状態を保持しない
レスポンス形式	JSONが主流（他にXML、YAMLもあり）
バージョン管理	`v1` , `v2` などURIやヘッダーで分離

深掘り解説

基本的な操作パターン：

  GET /users            → ユーザー一覧の取得
  GET /users/123        → ユーザー詳細の取得
  POST /users           → 新規ユーザーの作成
  PUT /users/123        → ユーザー情報の全更新
  PATCH /users/123      → ユーザー情報の一部更新
  DELETE /users/123     → ユーザーの削除

リソースの設計ルール：
- ```
/users/:id/orders
```
  → ユーザーごとの注文履歴
- ```
/products?limit=10&offset=20
```
  → ページネーション対応
- ```
/articles?sort=-createdAt
```
  → 並び順の変更

エラーレスポンスの形式：

  {
      "status": 400,
      "message": "Invalid email address",
      "code": "INVALID_EMAIL"
  }

HTTPステータスコード（例：400, 401, 404, 500）を正しく使い分けることが重要

応用・発展的な使い方

RESTfulなAPI設計のためのベストプラクティス：
- リソース設計を名詞で統一
- HTTPメソッドと意味を一致させる
- 不要なネストや冗長なURLは避ける
認証・認可の導入：
- JWTやOAuth 2.0などのトークンベース認証が主流
- 認可はエンドポイント単位または属性ベース制御（RBAC, ABAC）
OpenAPI（Swagger）による自動ドキュメント生成
- API仕様を
```
.yaml
```
  で定義 → Swagger UIでGUI確認と試行可能
GraphQLやgRPCとの使い分け：
- RESTはシンプルな構成に向く
- GraphQLは柔軟なクエリ、gRPCは高性能なバイナリ通信に強い

よくある誤解と注意点

REST＝JSONではない：フォーマットの選択は自由（ただしJSONが最も一般的）
REST APIだからといって「完璧な設計」になるわけではない：設計ポリシーが最重要
GETで副作用のある処理（DB更新など）を実装してしまうとRESTの原則に反する

まとめ

REST APIは、Webベースのサービス連携における事実上の標準です。
URLとHTTPメソッドによる直感的な設計は、学習コストも低く、規模を問わず幅広く使われています。
正しい設計原則と一貫したルールに基づいて構築すれば、拡張性・再利用性・保守性の高いAPIを実現できます。