REST API

REST APIについて

REST APIの使い方を復習したのでまとめておきます。

---

REST APIの基本

REST APIは、REST（Representational State Transfer）というアーキテクチャスタイルと、API（Application Programming Interface）というソフトウェア間の通信手段を組み合わせたものです。これは「RESTの原則に従って設計されたAPI」であり、Web上で異なるシステム同士がHTTPを使ってデータをやり取りする仕組みです。

RESTの原則（6つの制約）

RESTは、Roy Fielding博士が2000年の論文で提案した設計哲学です。REST APIは、この設計哲学に沿って設計されています。主な6つの制約は以下の通りです。

1. クライアント・サーバー構造
   • フロントエンド（クライアント）とバックエンド（サーバー）が分離されています 。
   • サーバーはデータの提供を担当し、クライアントはUI表示を担当します。
2. ステートレス（Stateless）
   • リクエスト間でサーバーがセッション状態を保持しません。
   • 必要な情報は毎回リクエストに含める必要があります。
3. キャッシュ可能
   • レスポンスをキャッシュすることで、効率化を図ることができます。
4. 統一インターフェース（Uniform Interface）
   • HTTPメソッド（GET, POST, PUT, DELETEなど）を役割ごとに使い分けます 。
   • リソース（URL）は名詞で表現します 。
5. 階層化システム（Layered System）
   • APIサーバーの背後にプロキシやロードバランサーなどを配置できます。
6. コードオンデマンド（任意）
   • 必要に応じてコード（JavaScriptなど）をクライアントに配信することが可能です 。

HTTPメソッドと役割（CRUD操作）

REST APIでは、HTTPメソッドをデータの操作（CRUD操作）に対応させて使用します。

• GET: データ取得 (Read)
  • 例: /users でユーザー一覧を取得
• POST: 新規作成 (Create)
  • 例: /users に新しいユーザーを追加
• PUT: 全体更新 (Update)
  • 例: /users/1 の全データを更新
• PATCH: 部分更新 (Partial Update)
  • 例: /users/1 の一部だけ更新
• DELETE: 削除 (Delete)
  • 例: /users/1 を削除

REST APIの例（TypeScript + Express）

提供されたソースでは、ExpressフレームワークとTypeScriptを用いたREST APIの具体的な実装例が示されています。

import express, { Request, Response } from "express";

const app = express();
app.use(express.json()); // JSONボディをパース

// GET: ユーザー一覧
app.get("/users", (req: Request, res: Response) => {
  res.json([{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]);
});

// POST: ユーザー作成
app.post("/users", (req: Request, res: Response) => {
  const newUser = req.body; // { name: "Charlie" }
  res.status(201).json(newUser); // HTTPステータスコード 201 (Created) を返す
});

// PUT: ユーザー更新
app.put("/users/:id", (req: Request, res: Response) => {
  res.json({ id: req.params.id, ...req.body }); // req.paramsでURLパラメータを取得
});

// DELETE: ユーザー削除
app.delete("/users/:id", (req: Request, res: Response) => {
  res.status(204).send();
});

app.listen(3000, () => console.log("REST API server running on port 3000"));

このコードでは、express.json()ミドルウェアがHTTPリクエストのJSONボディをreq.bodyに変換し、req.paramsがURLのパラメータ（例 /users/:id の id 部分）を取得するのに使われます。また、res.status()でHTTPステータスコードを設定し、res.json()でJSON形式のレスポンスを返します。

REST APIのメリット・デメリット

メリット

• HTTPベースであるため、Web上で広く利用可能です。
• シンプルで理解しやすいです。
• キャッシュやスケーリングがしやすいです 。

デメリット

• 複雑な検索や関係性のあるデータ取得において、リクエストが冗長になりやすい場合があります。
• 固定的なエンドポイント構造が柔軟性に欠けることがあります（GraphQLの方が柔軟な場合があります)。

REST APIへのアクセス方法

REST APIにアクセスするには、主に以下のツールやAPIが使用されます。

1. curlコマンド (ターミナル用)
   • curl -X GET http://localhost:3000/users でユーザー一覧を取得。
   • curl -X POST http://localhost:3000/users -H "Content-Type: application/json" -d '{"name": "Charlie"}' で新しいユーザーを作成できます。
     • -X POST はHTTPメソッドをPOSTに指定し、-H はヘッダー設定（JSONを送信することの宣言)、-d はデータ部分（JSON文字列）を指定します。
2. fetch API (ブラウザ / Node.js用)
   • JavaScript標準のHTTP通信APIで、Node.js v18以降やブラウザで利用可能です。
   • 例えば、fetch("http://localhost:3000/users") でGETリクエストを送信し、fetch("http://localhost:3000/users", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ name: "Charlie" }) }) のようにPOSTリクエストを送信できます。
   • REST APIのテストでは、まずcurlやPostmanで試すのが一般的です。

CORS（Cross-Origin Resource Sharing）

ブラウザからREST APIにアクセスする場合、**CORS（Cross-Origin Resource Sharing）**の設定が必要になることがあります。

• オリジンとは、スキーム（http/https）、ドメイン、ポートの組み合わせを指します。
• ブラウザはセキュリティ上の制約から、異なるオリジンへの直接アクセスを制限しています。
• サーバー側でAccess-Control-Allow-Originヘッダーを設定することで、特定のオリジンや全てのオリジンからのアクセスを許可できるようになります。

ExpressにCORSを追加する方法

corsパッケージを使用するのが一般的です。

import express, { Request, Response } from "express";
import cors from "cors"; // CORS用ミドルウェア

const app = express();

// ① 全てのオリジンを許可（開発時用）
app.use(cors()); //

/*
// ② 特定のオリジンだけ許可（本番向け）
app.use(cors({
  origin: "https://example.com", // 許可するフロントエンドのURL
  methods: ["GET", "POST", "PUT", "DELETE"], // 許可するHTTPメソッド
  allowedHeaders: ["Content-Type", "Authorization"], // 許可するヘッダー
}));
*/

// ... (REST APIのエンドポイントのコードが続く) ...

app.listen(3000, () => console.log("Server running on port 3000"));

corsパッケージはnpmでインストールできます (npm install cors、npm install --save-dev @types/cors) 。app.use(cors())とすることで、全てのオリジンからのアクセスを許可できますが、本番環境ではoriginオプションを使って特定のURLのみを許可し、セキュリティを強化することが推奨されます。

CORS設定がないとどうなるか？

app.use(cors())が削除された状態でブラウザからアクセスしようとすると、以下のようなCORSエラーが発生します。

Access to fetch at 'http://localhost:3000/users' from origin 'http://127.0.0.1:5500' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

これはブラウザによるクロスオリジン制限のためであり、CORS設定はブラウザからのアクセス時に重要です。