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の主な原則（制約）

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

これらを理解しておくことで、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を設計できます。
ぜひ、設計のベストプラクティスを自サービスに取り入れてみてください。