REST API 入門 ～ 基本概念から設計・実装のポイントまで

REST API（Representational State Transfer API）は、Web サービスの設計や実装において非常に人気のあるアーキテクチャスタイルです。
この記事では、REST API の基本概念、設計の原則、実装時の注意点、そして実際の開発で役立つベストプラクティスについて、具体例を交えながら分かりやすく解説します。

1. REST API とは？

REST は、「Representational State Transfer」の略で、Web アプリケーションやサービスが通信するための一連の設計原則を指します。
REST API は、HTTP プロトコルをベースにし、クライアントとサーバー間でリソース（データ）の状態を表現し、操作するためのインターフェースを提供します。

REST の主な特徴

ステートレス性

各リクエストは独立しており、サーバー側はリクエスト間の状態を保持しません。これにより、スケーラブルなシステムが構築しやすくなります。

リソース指向

API のエンドポイントは、データ（リソース）を一意に識別できる URI で表現されます。たとえば、/users/123 は ID が 123 のユーザー情報を表します。

HTTP メソッドの活用:

一般に、REST API では以下の HTTP メソッドが使われます。
• GET: リソースの取得
• POST: 新しいリソースの作成
• PUT/PATCH: 既存リソースの更新
• DELETE: リソースの削除
• 統一インターフェース:
クライアントとサーバーが標準化されたインターフェース（HTTP ステータスコード、メディアタイプなど）を共有することで、柔軟かつ拡張性の高いシステムが実現されます。

2. REST API の設計原則

REST API を設計する際に覚えておきたい原則を以下に示します。

2.1 リソースの一意性と階層構造

一意な識別子:

各リソースは固有の URL（エンドポイント）でアクセスできるように設計します。
例：/products/456 は ID が 456 の製品情報に対応します。

階層的な URL:

リソース間の関係性を URL の階層構造で表現します。
例：/users/123/orders は、ID 123 のユーザーの注文一覧を表す。

2.2 HTTP メソッドとステータスコードの適切な利用

メソッドの使い分け

リソースの取得には GET、作成には POST、更新には PUT/PATCH、削除には DELETE を使用します。

ステータスコード

リクエストの結果に応じた適切な HTTP ステータスコードを返すことが大切です。
例：成功時は 200 番台、入力エラー時は 400 番台、認証エラー時は 401 や 403、サーバーエラー時は 500 番台。

2.3 データフォーマットとメディアタイプ

JSON

多くの場合、データのやり取りには JSON 形式が使われます。

Content-Type ヘッダー

クライアントとサーバーは、Content-Type: application/json のようなヘッダーを通じて、送受信するデータの形式を明確にします。

2.4 セキュリティと認証

HTTPS

データのやり取りは必ず HTTPS を使用し、通信の暗号化を行います。

認証・認可

認証トークン（例：JWT）や API キーを用いて、リクエストを適切に認証・認可します。

3. REST API の実装例

ここでは、シンプルな REST API を Node.js と Express を使って実装する例を示します。
※ここに書いているのはBackendのExpressのみ。Frontendからリクエストし、レスポンスを受け取る実装を行う必要があります。

3.1 サンプルコード

// server.js
const express = require("express");
const app = express();
app.use(express.json());

let products = [
  { id: 1, name: "製品A", price: 1000 },
  { id: 2, name: "製品B", price: 2000 },
  { id: 3, name: "製品C", price: 3000 },
];

// GET /products - 製品一覧を取得
app.get("/products", (req, res) => {
  res.json(products);
});

// GET /products/:id - 特定の製品を取得
app.get("/products/:id", (req, res) => {
  const product = products.find(p => p.id === parseInt(req.params.id));
  if (product) {
    res.json(product);
  } else {
    res.status(404).json({ error: "製品が見つかりません" });
  }
});

// POST /products - 新しい製品を作成
app.post("/products", (req, res) => {
  const newProduct = {
    id: products.length + 1,
    name: req.body.name,
    price: req.body.price,
  };
  products.push(newProduct);
  res.status(201).json(newProduct);
});

// PUT /products/:id - 製品情報を更新
app.put("/products/:id", (req, res) => {
  const product = products.find(p => p.id === parseInt(req.params.id));
  if (product) {
    product.name = req.body.name;
    product.price = req.body.price;
    res.json(product);
  } else {
    res.status(404).json({ error: "製品が見つかりません" });
  }
});

// DELETE /products/:id - 製品を削除
app.delete("/products/:id", (req, res) => {
  products = products.filter(p => p.id !== parseInt(req.params.id));
  res.status(204).end();
});

app.listen(3000, () => {
  console.log("サーバーはポート 3000 で起動中");
});

3.2 このコードのポイント

エンドポイントの設計

URL の階層構造を利用して、製品一覧や特定の製品情報にアクセスできるようにしています。

HTTP メソッドの適切な使用

GET、POST、PUT、DELETE を用いることで、リソースの取得、作成、更新、削除が明確に区別されています。

エラーハンドリング

リクエストに対する適切な HTTP ステータスコード（404 や 204 など）を返すことで、クライアントがレスポンスの状態を正しく判断できるようになっています。

4. REST API 設計のベストプラクティス

ドキュメンテーション

API ドキュメント（Swagger、OpenAPI 仕様など）を作成し、利用者に API の使い方を明確に伝えましょう。

バージョニング

API の変更に備えて、エンドポイントにバージョン番号を含める（例：/api/v1/products）ことを検討しましょう。

一貫性

リクエストとレスポンスのフォーマット、エラーメッセージの形式などを一貫させることで、クライアント側の実装が楽になります。

セキュリティ

認証と認可の仕組みを取り入れ、API キーやトークンによるアクセス制御を行うとともに、HTTPS を必ず利用しましょう。

5. まとめ

REST API は、シンプルで柔軟な Web サービスの設計を可能にします。

基本概念

ステートレス性、リソース指向、統一されたインターフェースが REST の根幹です。

設計原則

一意なリソース識別子、HTTP メソッドとステータスコードの適切な利用、そしてセキュリティが重要です。

実装例

Node.js と Express を用いたサンプルコードを参考に、API の各エンドポイントでの基本操作（GET, POST, PUT, DELETE）を実装できます。

これらのポイントを押さえることで、拡張性が高く、メンテナンスしやすい REST API を構築できます。プロジェクトの要件に合わせて設計・実装を進め、ユーザーや開発者にとって使いやすい Web サービスを実現してください。