RESTful API 実践

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

1. 認証と認可

// 使用 JWT Token 进行身份验证
GET /api/users/profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

// API 响应包含用户权限检查
{
  "success": true,
  "data": {
    "id": 123,
    "name": "张三",
    "role": "user"
  }
}

2. 入力検証

// 服务器端验证示例
POST /api/users
{
  "email": "[email protected]",
  "password": "123"  // 密码太短
}

// 验证失败响应
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "密码长度至少为8位"
  }
}

3. HTTPSとデータ暗号化

✅ https://api.example.com/users
❌ http://api.example.com/users

パフォーマンス最適化の実践

1. データのページネーション

// 避免一次返回大量数据
GET /api/users?page=1&limit=20

{
  "success": true,
  "data": [...], // 只返回20条记录
  "pagination": {
    "currentPage": 1,
    "totalPages": 50,
    "totalItems": 1000
  }
}

2. フィールドのフィルタリング

// 只返回需要的字段
GET /api/users?fields=id,name,email

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "张三",
      "email": "[email protected]"
      // 不返回其他不需要的字段
    }
  ]
}

3. キャッシュ戦略

// 使用缓存头
GET /api/users/123
Cache-Control: max-age=3600  // 缓存1小时

// 条件请求
GET /api/users/123
If-None-Match: "etag-value"

// 304 Not Modified (数据未变化)

エラーハンドリングのベストプラクティス

統一されたエラーフォーマット

{
  "success": false,
  "error": {
    "code": "SPECIFIC_ERROR_CODE",    // 机器可读的错误码
    "message": "用户友好的错误信息",      // 人类可读的错误信息
    "details": {...},                // 详细错误信息（可选）
    "timestamp": "2024-01-15T10:00:00Z"
  }
}

一般的なエラーコードの設計

const ERROR_CODES = {
  // 4xx 客户端错误
  'VALIDATION_ERROR': 400,        // 数据验证失败
  'UNAUTHORIZED': 401,            // 未授权
  'FORBIDDEN': 403,              // 禁止访问
  'NOT_FOUND': 404,              // 资源不存在
  'METHOD_NOT_ALLOWED': 405,     // 方法不允许
  'CONFLICT': 409,               // 资源冲突
  
  // 5xx 服务器错误
  'INTERNAL_ERROR': 500,         // 内部服务器错误
  'SERVICE_UNAVAILABLE': 503     // 服务不可用
}

APIのドキュメント化

標準化されたドキュメント形式の使用

OpenAPI（Swagger）仕様の使用を推奨します：

# swagger.yaml 示例
openapi: 3.0.0
info:
  title: 用户管理 API
  version: 1.0.0
  description: 提供用户的增删改查功能

paths:
  /api/users:
    get:
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          description: 页码
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'

バージョン管理戦略

URLバージョン管理（推奨）

// 版本1
GET /api/v1/users

// 版本2（新增字段，保持向后兼容）
GET /api/v2/users
{
  "id": 1,
  "name": "张三",
  "email": "[email protected]",
  "avatar": "https://example.com/avatar.jpg"  // 新增字段
}

互換性の処理

// 保持向后兼容的策略
{
  "deprecationWarning": "该 API 版本将在2024年6月1日后停止支持，请升级到 v2",
  "data": {...}
}

実践演習

演習1：図書管理システムAPI

以下の機能を含むシンプルな図書管理システムを設計します：

要件分析

図書情報の管理（タイトル、著者、ISBN、価格）
図書カテゴリの管理
図書の追加・削除・変更・検索（CRUD）をサポート
カテゴリごとの図書フィルタリングをサポート

API設計演習

以下のAPIエンドポイントを設計してください：

// 你的任务：完善以下 API 设计

// 图书相关
GET    /api/books                    // 获取图书列表
GET    /api/books/{id}              // 获取特定图书
POST   /api/books                   // 创建新图书
PUT    /api/books/{id}              // 更新图书信息
DELETE /api/books/{id}              // 删除图书

// 分类相关
GET    /api/categories              // 获取分类列表
GET    /api/categories/{id}/books   // 获取分类下的图书

サンプルデータ構造：

{
  "id": 1,
  "title": "JavaScript 高级程序设计",
  "author": "Nicholas C. Zakas",
  "isbn": "9787115275790",
  "price": 99.00,
  "categoryId": 1,
  "category": {
    "id": 1,
    "name": "编程技术"
  },
  "publishedDate": "2012-03-01",
  "description": "深入理解JavaScript语言",
  "stock": 50
}

演習タスク

APIドキュメントの設計：各エンドポイントの詳細なリクエストとレスポンスの例を作成する
エラーハンドリング：さまざまなエラー状況のレスポンス形式を設計する
データ検証：各フィールドの検証ルールを列挙する
テストケース：各APIをテストするためのcurlコマンドを作成する

演習2：Todo API

Todo管理APIを作成します：

機能要件

Todoの作成、表示、更新、削除
タスクの完了状態のマーク
ステータスによるタスクのフィルタリング
タスクの優先度をサポート

データモデルの設計

{
  "id": 1,
  "title": "学习 RESTful API",
  "description": "完成 API 教程的学习",
  "status": "pending",  // pending, completed, cancelled
  "priority": "high",   // low, medium, high
  "dueDate": "2024-01-20",
  "createdAt": "2024-01-15T08:00:00Z",
  "updatedAt": "2024-01-15T08:00:00Z"
}

チャレンジタスク

一括操作：タスクのステータスを一括更新するAPIの設計
検索機能：タイトルと説明による検索をサポート
統計情報：タスク完了状況の統計データを返す

演習3：ソーシャルメディアAPI

簡易版ソーシャルメディアプラットフォームのAPIを設計します：

コア機能

ユーザー登録とログイン
投稿の公開と閲覧
他のユーザーのフォロー
いいねとコメント

API構造の設計

// 用户相关
POST /api/auth/register     // 用户注册
POST /api/auth/login        // 用户登录
GET  /api/users/profile     // 获取个人资料

// 动态相关
GET  /api/posts            // 获取动态列表
POST /api/posts            // 发布新动态
GET  /api/posts/{id}       // 获取特定动态
DELETE /api/posts/{id}     // 删除动态

// 互动相关
POST /api/posts/{id}/like     // 点赞动态
POST /api/posts/{id}/comments // 添加评论
GET  /api/posts/{id}/comments // 获取评论列表

高度な機能の設計

フォローシステム：ユーザー間のフォロー関係
メッセージプッシュ：新しいインタラクションの通知メカニズム
コンテンツモデレーション：センシティブなコンテンツのフィルタリング

その他の拡張