【初心者向け】プログラミングの「REST API」基礎知識

みなさん、プログラミングを学んでいて「API」という言葉をよく聞くけれど、具体的に何なのかよく分からないと思ったことはありませんか？

特に「REST API」は、現代のWeb開発において最も重要な概念の一つです。 ソーシャルメディア、ECサイト、スマホアプリなど、私たちが日常的に使うサービスのほとんどがREST APIを使って作られています。

この記事では、プログラミング初心者向けにREST APIの基本概念から実装方法まで、具体例を交えながら分かりやすく解説します。 難しそうに見えるREST APIも、基本を理解すれば実はとてもシンプルな仕組みです。

APIとは何か

まず、APIの基本概念から理解していきましょう。

APIの基本的な意味

API（Application Programming Interface）とは、異なるソフトウェア同士がやり取りするための窓口のことです。

簡単に言うと、「アプリケーション同士が話し合うためのルール」という感じです。 例えば、スマホの天気アプリが気象データを取得するとき、気象庁のサーバーとAPIを通じてデータをやり取りしています。

日常生活での例え

レストランで注文することを例に考えてみましょう。

お客さん（アプリ）が注文（リクエスト）をウェイター（API）に伝えると、ウェイターがキッチン（サーバー）に注文を届けます。 キッチンで料理（データ）ができると、ウェイターがお客さんに料理を運んできます（レスポンス）。

このとき、お客さんは直接キッチンに入る必要がなく、ウェイターを通じて欲しいものを手に入れることができます。

Web開発におけるAPIの役割

Web開発では、フロントエンド（画面部分）とバックエンド（サーバー部分）がAPIを通じて連携します。

ユーザーが画面でボタンをクリックすると、フロントエンドがAPIを呼び出し、サーバーからデータを取得して画面に表示します。 この仕組みにより、ユーザーが快適にWebサービスを利用できるのです。

RESTとは

REST APIの「REST」について詳しく説明します。

RESTの正式名称と基本概念

REST（Representational State Transfer）は、Web サービスを設計するための一連の原則です。

2000年にロイ・フィールディングによって提唱された設計原則で、シンプルで理解しやすいAPI設計を目指しています。 RESTに従って設計されたAPIを「RESTful API」または「REST API」と呼びます。

RESTの6つの原則

RESTには以下の原則があります。

ステートレス: サーバーはクライアントの状態を記憶しません 統一インターフェース: 一貫したルールでやり取りを行います 階層システム: 複数のサーバーが階層的に配置されても動作します キャッシュ可能: データをキャッシュして効率化できます クライアント・サーバー分離: フロントエンドとバックエンドが独立しています コードオンデマンド: 必要に応じてコードをダウンロードできます（オプション）

これらの原則により、拡張性が高く、保守しやすいAPIを設計できます。

RESTが人気な理由

RESTが広く採用される理由を説明します。

シンプルで理解しやすく、HTTP の標準的な機能を活用するため実装が容易です。 また、プラットフォームや言語に依存せず、多様なクライアントから利用できます。

HTTPメソッドの理解

REST APIで使用される主要なHTTPメソッドについて説明します。

GET - データの取得

GETは、サーバーからデータを取得するためのメソッドです。

// ユーザー情報を取得する例
fetch('/api/users/123')
  .then(response => response.json())
  .then(user => {
    console.log('ユーザー名:', user.name);
    console.log('メール:', user.email);
  });

このコードは、ID が 123 のユーザー情報をサーバーから取得しています。 GETリクエストは、データを変更せず、単純に情報を読み取るだけです。

POST - データの作成

POSTは、新しいデータをサーバーに送信して作成するためのメソッドです。

// 新しいユーザーを作成する例
const newUser = {
  name: '田中太郎',
  email: 'tanaka@example.com',
  age: 25
};

fetch('/api/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(newUser)
})
.then(response => response.json())
.then(result => {
  console.log('作成されたユーザーID:', result.id);
});

POSTリクエストでは、作成したいデータをリクエストボディに含めて送信します。

PUT - データの更新

PUTは、既存のデータを完全に更新するためのメソッドです。

// ユーザー情報を更新する例
const updatedUser = {
  name: '田中次郎',
  email: 'tanaka.jiro@example.com',
  age: 26
};

fetch('/api/users/123', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(updatedUser)
})
.then(response => response.json())
.then(result => {
  console.log('更新完了:', result);
});

PUTでは、リソース全体を新しいデータで置き換えます。

DELETE - データの削除

DELETEは、指定したデータを削除するためのメソッドです。

// ユーザーを削除する例
fetch('/api/users/123', {
  method: 'DELETE'
})
.then(response => {
  if (response.ok) {
    console.log('ユーザーが削除されました');
  }
});

DELETEリクエストは、通常データを送信する必要がなく、URLで削除対象を指定します。

RESTful URLの設計

適切なURL設計について説明します。

リソース指向の設計

REST APIでは、URLはリソース（データの塊）を表すように設計します。

動詞ではなく名詞を使い、リソースの階層構造を明確に表現します。 例えば、ユーザーに関するAPIなら /api/users のようにリソース名を複数形で表現します。

具体的なURL設計例

実際のWebサービスを想定したURL設計例を紹介します。

# ユーザー関連 GET /api/users # ユーザー一覧を取得 GET /api/users/123 # 特定のユーザーを取得 POST /api/users # 新しいユーザーを作成 PUT /api/users/123 # ユーザー情報を更新 DELETE /api/users/123 # ユーザーを削除 # 投稿関連 GET /api/posts # 投稿一覧を取得 GET /api/posts/456 # 特定の投稿を取得 POST /api/posts # 新しい投稿を作成 PUT /api/posts/456 # 投稿を更新 DELETE /api/posts/456 # 投稿を削除 # ユーザーの投稿（ネストしたリソース） GET /api/users/123/posts # 特定ユーザーの投稿一覧 POST /api/users/123/posts # 特定ユーザーの新しい投稿を作成

このように、リソースの関係性をURLで表現することで、直感的に理解しやすいAPIになります。

クエリパラメータの活用

データの絞り込みや並び替えには、クエリパラメータを使用します。

# 検索・フィルタリング GET /api/users?name=田中 # 名前で検索 GET /api/users?age=25&city=東京 # 年齢と都市で絞り込み # ページネーション GET /api/users?page=2&limit=10 # 2ページ目、1ページ10件 # ソート GET /api/users?sort=created_at&order=desc # 作成日時の降順

クエリパラメータを使うことで、柔軟なデータ取得が可能になります。

JSONデータ形式

REST APIで主に使用されるJSON形式について説明します。

JSONの基本構造

JSON（JavaScript Object Notation）は、データをテキスト形式で表現する軽量なフォーマットです。

{
  "id": 123,
  "name": "田中太郎",
  "email": "tanaka@example.com",
  "age": 25,
  "isActive": true,
  "tags": ["プログラマー", "初心者"],
  "profile": {
    "bio": "プログラミングを勉強中です",
    "website": "https://tanaka.example.com"
  }
}

このように、文字列、数値、真偽値、配列、オブジェクトなどを組み合わせてデータを表現できます。

APIレスポンスの設計

API のレスポンスは、一貫した形式で設計することが重要です。

{
  "success": true,
  "data": {
    "id": 123,
    "name": "田中太郎",
    "email": "tanaka@example.com"
  },
  "message": "ユーザー情報を正常に取得しました"
}

成功・失敗の情報、実際のデータ、メッセージを含む形式にすることで、クライアント側での処理が容易になります。

エラーレスポンスの設計

エラーが発生した場合のレスポンス形式も統一します。

{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "指定されたユーザーが見つかりません"
  },
  "details": {
    "userId": 999,
    "timestamp": "2025-07-05T10:00:00Z"
  }
}

エラーコード、メッセージ、詳細情報を含むことで、適切なエラーハンドリングが可能になります。

ステータスコードの理解

HTTPステータスコードの意味と使い分けについて説明します。

主要なステータスコード

REST APIでよく使用されるステータスコードを紹介します。

200 OK: リクエストが成功し、期待されたレスポンスを返す 201 Created: リソースの作成が成功した 204 No Content: リクエストは成功したが、返すコンテンツがない（削除時など） 400 Bad Request: リクエストの形式が不正 401 Unauthorized: 認証が必要または認証に失敗 403 Forbidden: アクセス権限がない 404 Not Found: 指定されたリソースが見つからない 500 Internal Server Error: サーバー内部でエラーが発生

これらのコードを適切に使い分けることで、クライアント側で適切な処理を行えます。

コード例でのステータスコード利用

実際のAPI実装でのステータスコードの使い方を示します。

// Express.js でのAPI実装例
app.get('/api/users/:id', (req, res) => {
  const userId = req.params.id;
  
  // ユーザーを検索
  const user = findUserById(userId);
  
  if (!user) {
    // ユーザーが見つからない場合
    return res.status(404).json({
      success: false,
      error: {
        code: 'USER_NOT_FOUND',
        message: '指定されたユーザーが見つかりません'
      }
    });
  }
  
  // 正常な場合
  res.status(200).json({
    success: true,
    data: user
  });
});

このように、状況に応じて適切なステータスコードを返すことが重要です。

実践的なREST API作成

簡単なREST APIを実際に作成してみましょう。

基本的なAPI構成

Node.js と Express.js を使った簡単なTODO管理APIを作成します。

const express = require('express');
const app = express();

// JSONパースのミドルウェア
app.use(express.json());

// メモリ上でのデータ保存（実際の開発ではデータベースを使用）
let todos = [
  { id: 1, title: '買い物', completed: false },
  { id: 2, title: '勉強', completed: true }
];
let nextId = 3;

// TODO一覧を取得
app.get('/api/todos', (req, res) => {
  res.status(200).json({
    success: true,
    data: todos
  });
});

// 特定のTODOを取得
app.get('/api/todos/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const todo = todos.find(t => t.id === id);
  
  if (!todo) {
    return res.status(404).json({
      success: false,
      error: { message: 'TODOが見つかりません' }
    });
  }
  
  res.status(200).json({
    success: true,
    data: todo
  });
});

この基本的な実装では、GET メソッドでTODOの取得を行っています。

データ作成・更新・削除の実装

POST、PUT、DELETE メソッドの実装例を紹介します。

// 新しいTODOを作成
app.post('/api/todos', (req, res) => {
  const { title } = req.body;
  
  if (!title) {
    return res.status(400).json({
      success: false,
      error: { message: 'タイトルは必須です' }
    });
  }
  
  const newTodo = {
    id: nextId++,
    title: title,
    completed: false
  };
  
  todos.push(newTodo);
  
  res.status(201).json({
    success: true,
    data: newTodo
  });
});

// TODOを更新
app.put('/api/todos/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const { title, completed } = req.body;
  
  const todoIndex = todos.findIndex(t => t.id === id);
  
  if (todoIndex === -1) {
    return res.status(404).json({
      success: false,
      error: { message: 'TODOが見つかりません' }
    });
  }
  
  todos[todoIndex] = {
    id: id,
    title: title || todos[todoIndex].title,
    completed: completed !== undefined ? completed : todos[todoIndex].completed
  };
  
  res.status(200).json({
    success: true,
    data: todos[todoIndex]
  });
});

// TODOを削除
app.delete('/api/todos/:id', (req, res) => {
  const id = parseInt(req.params.id);
  const todoIndex = todos.findIndex(t => t.id === id);
  
  if (todoIndex === -1) {
    return res.status(404).json({
      success: false,
      error: { message: 'TODOが見つかりません' }
    });
  }
  
  todos.splice(todoIndex, 1);
  
  res.status(204).send(); // コンテンツなしで成功を返す
});

// サーバー起動
const PORT = 3000;
app.listen(PORT, () => {
  console.log(`サーバーがポート${PORT}で起動しました`);
});

これで完全なCRUD（作成・読み取り・更新・削除）操作が可能なREST APIが完成します。

セキュリティとベストプラクティス

REST API開発で注意すべきセキュリティ対策とベストプラクティスを説明します。

認証と認可

API のセキュリティには、認証（Authentication）と認可（Authorization）が重要です。

// JWTトークンを使った認証の例
const jwt = require('jsonwebtoken');

// 認証ミドルウェア
const authenticateToken = (req, res, next) => {
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1];
  
  if (!token) {
    return res.status(401).json({
      success: false,
      error: { message: '認証トークンが必要です' }
    });
  }
  
  jwt.verify(token, process.env.JWT_SECRET, (err, user) => {
    if (err) {
      return res.status(403).json({
        success: false,
        error: { message: '無効なトークンです' }
      });
    }
    req.user = user;
    next();
  });
};

// 保護されたエンドポイントの例
app.get('/api/protected', authenticateToken, (req, res) => {
  res.json({
    success: true,
    message: '認証されたユーザーのみアクセス可能',
    user: req.user
  });
});

このように、機密情報や重要な操作には適切な認証を実装します。

入力値検証

ユーザーからの入力は必ず検証し、不正なデータを排除します。

// バリデーション用ライブラリ（joi）を使った例
const Joi = require('joi');

const userSchema = Joi.object({
  name: Joi.string().min(2).max(50).required(),
  email: Joi.string().email().required(),
  age: Joi.number().integer().min(0).max(150)
});

app.post('/api/users', (req, res) => {
  const { error, value } = userSchema.validate(req.body);
  
  if (error) {
    return res.status(400).json({
      success: false,
      error: {
        message: '入力値が無効です',
        details: error.details
      }
    });
  }
  
  // バリデーション済みのデータで処理を続行
  const newUser = createUser(value);
  res.status(201).json({ success: true, data: newUser });
});

適切なバリデーションにより、セキュリティリスクを大幅に減らすことができます。

レート制限とCORS

API の悪用を防ぐためのレート制限と、ブラウザからのアクセスを制御するCORSの設定も重要です。

const rateLimit = require('express-rate-limit');
const cors = require('cors');

// レート制限の設定
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15分
  max: 100, // 最大100リクエスト
  message: {
    success: false,
    error: { message: 'リクエスト制限に達しました' }
  }
});

// CORS設定
const corsOptions = {
  origin: ['http://localhost:3000', 'https://myapp.com'],
  optionsSuccessStatus: 200
};

app.use(limiter);
app.use(cors(corsOptions));

これらの設定により、API の安全性と安定性を向上させることができます。

まとめ

REST APIは、現代のWeb開発において不可欠な技術です。

HTTPメソッド、適切なURL設計、JSONデータ形式、ステータスコードの理解が基本となります。 また、セキュリティ対策や入力値検証も重要な要素です。

最初は複雑に感じるかもしれませんが、基本的な原則を理解し、実際に手を動かして練習することで必ず身につけることができます。 まずは簡単なTODOアプリのAPIから始めて、徐々に機能を拡張していくことをおすすめします。

ぜひ、この記事で学んだ内容を参考に、実際にREST APIを作成してみてください。 きっと、Web開発の理解が深まり、より高度なアプリケーション開発に取り組めるようになるはずです。