REST API を使って設計するために必要な知識諸々

REST API設計入門

対象：バックエンド／フルスタックエンジニア初心者～中級者
目的：REST／Web APIの設計を整理し、「我流」ではなく体系的に理解する

はじめに

Webサービスが発展する中で、クライアント（Web／モバイル）とサーバー（API）の分離が進み、API設計の重要性が増しています。
本記事では、RESTアーキテクチャの理解から、実践的なWeb API設計のポイントまでを整理します。

この記事の対象者

• API設計に触れたことはあるが、自分なりの設計ルールを持てていない方
• サーバー・クライアント分離の開発、マイクロサービス／フロントバック分離型でAPI設計を行っている方
• これからAPIを自社サービスで設計・実装しようとしている方

この記事の目標

• REST／RESTfulという言葉の意味を整理する
• URI設計、HTTPメソッド、パラメーター、レスポンスフォーマット等、Web API設計の具体的なルールを知る
• 認証・エラー・セキュリティなど設計における「その他の考慮点」まで触れる

この記事で扱わないこと

コードレベル（フレームワーク固有）の実装詳細（例えばSpring BootやNestJSの具体的なコントローラ実装）は扱いません。
あくまでも「設計（仕様・ルール）」の観点にフォーカスします。

APIとは／Web APIとは

APIとは

API（Application Programming Interface）とは、機能を持つソフトウェアコンポーネントを外部から呼び出すための「仕様」です。

Web APIとは

Web APIとは、特にHTTPプロトコルを介してネットワーク越しにアクセスするAPIを指します。

例：URIにアクセスしてデータの取得・更新を行えるシステム。

RESTについて

RESTとは

REST（Representational State Transfer）は、Roy Fielding 氏が提唱した分散システムにおける設計原則のひとつで、Webシステムに適用された設計様式を指します。

RESTfulとは

RESTの原則に従って設計されたAPIを「RESTful API」と呼びます。

RESTの主な原則（制約）

1. クライアント-サーバー制約：クライアントとサーバーを分離し、それぞれ独立に進化可能にする。
2. ステートレス：リクエストごとに必要な情報をすべて含み、状態をサーバーに保持しない。
3. キャッシュ可能性：クライアントやインターミディエイトがキャッシュできる設計をサポート。
4. 統一インターフェース：リソースをURIで一意に表現し、HTTPメソッドなどで操作を統一。
5. レイヤーシステム：多層アーキテクチャ（ゲートウェイ、ロードバランサー、APIサーバー等）を可能にする。
6. コードオンデマンド（任意）：クライアントへコードをダウンロードして実行させることを許可する。

これらを理解しておくことで、API設計の「なぜこうするか」が明確になります。

Web API設計（実践）

URI設計

良いURI設計のルール例を挙げます。

• 短くて入力しやすい
• 省略しない（意味を持たない略語を使わない）
• 小文字で統一、大文字を使わない
• 単語はハイフン（-）でつなぐ
• リソース名は複数形で表現
• URIにエンコードが必要な文字を使わない
• 更新・拡張しやすい構造にする
• パスパラメーター／クエリパラメーターの使い分けルールを統一する

例として：

❌ BAD: https://example.com/service/api/search
✅ GOOD: https://example.com/search

さらに、複数形・ハイフン・小文字での統一なども重要です。

HTTPメソッド

リソースに対してどのような操作を行うかをHTTPメソッドで表現します。代表的なものは：

メソッド	処理内容
GET	リソースの取得
POST	リソースの新規登録
PUT	既存リソースの更新
DELETE	リソースの削除

例えば、リソース /api/v1/posts/1 に対し：

• GET /api/v1/posts/1 → 記事ID1を取得
• PUT /api/v1/posts/1 → 記事ID1を更新

クエリパラメーターとパスパラメーター

• パスパラメーター：リソースを一意に参照するとき（例：/posts/1）
• クエリパラメーター：省略可能・フィルタリング・検索時などに（例：/users?name=tanaka）

明確に使い分けることで、APIの意図・構造が分かりやすくなります。

ステータスコード

HTTPステータスコードを適切に使うことは重要です。

• 2xx：成功
• 4xx：クライアント側の誤り
• 5xx：サーバー側の誤り

エラー時には、ステータスコードだけでなく、レスポンスボディで詳細を返す設計が望ましいです。

レスポンスデータのフォーマット

主にJSONが現代Web APIでは主流です（XMLも使われることがありますが、冗長なためJSONが好まれます）。

レスポンス設計のポイント

エンベロープ（header/result構造）をあえて使わない設計が推奨される場合があります。

// ❌ BAD
{
  "header": {
    "code": "0",
    "message": "success"
  },
  "result": {
    "books": [
      { "id":1, "name":"〜", "price":3000 },
      { "id":2, "name":"〜", "price":1500 }
    ]
  }
}

// ✅ GOOD
{
  "books": [
    { "id":1, "name":"〜", "price":3000 },
    { "id":2, "name":"〜", "price":1500 }
  ]
}

• ネスト構造を最小化する → 可読性／通信量に影響します
• プロパティの命名規則を統一（例：camelCase／snake_case）
• 日付などのフォーマットは標準化（例：RFC3339形式 2022-10-31T18:00:00+09:00）

エラー設計

エラー時のレスポンスもルール化しておくべきです。

{
  "code": "12345",
  "message": "認証エラーです"
}

• HTML形式でエラーを返さない（クライアント処理できなくなる可能性あり）
• ステータスコード + ボディでエラー内容を明示

認証／認可

API設計時には認証・認可も重要な検討項目です。

JWT（JSON Web Token）

サーバー側でセッションを保持しない「ステートレス」な方式として利用されることが多いです。

• JWTの構成：ヘッダー → ペイロード → 署名
• Authorizationヘッダー経由での送信が一般的です。

Authorization: Bearer <token>

セキュリティ

APIを設計・公開する際、セキュリティ対策も必須です。主なポイント：

• XSS（クロスサイトスクリプティング）対策
• CSRF（クロスサイトリクエストフォージェリ）対策
• 通信の暗号化（HTTPS必須）
• JWT等を使う場合、署名アルゴリズムを none にしない等検証を厳格に

最後に

いかがでしたでしょうか。API設計というとコード実装ばかりに目が行きがちですが、設計のルールや原則をしっかり押さえておくことで、拡張性・保守性の高いAPIを設計できます。
ぜひ、設計のベストプラクティスを自サービスに取り入れてみてください。