REST(Representational State Transfer)は、ネットワークアプリケーションのインターフェースを設計するためのソフトウェアアーキテクチャスタイルです。

REST API(Application Programming Interface)は REST 原則に基づいて構築された Web サービスインターフェースであり、異なるシステムが HTTP プロトコルを介して通信およびデータ交換を行うことを可能にします。

REST APIの核心的な特徴は以下の通りです:

  • ステートレス性(Stateless):各リクエストには、そのリクエストの処理に必要なすべての情報が含まれます
  • リソース指向(Resource-based):すべてのデータはリソースとみなされ、URIで識別されます
  • 统一接口(Uniform Interface):使用标准 HTTP 方法(GET、POST、PUT、DELETE 等)
  • キャッシュ可能性(Cacheable):レスポンスはキャッシュ可能またはキャッシュ不可として明確にマークできます

REST APIの核心的な概念

1. 资源(Resource)

RESTでは、リソースとはユーザー、製品、注文など、名前を付けることができる任意の情報です。各リソースには一意の識別子(URI)があります。

2. HTTP 方法

REST APIは標準的なHTTPメソッドを使用してリソースに対する操作を定義します:

HTTP 方法 描述 幂等性 安全性
GET 获取资源 である である
POST 创建新资源 否 否
PUT リソース全体を更新する である 否
PATCH リソースを部分的に更新する 否 否
DELETE 删除资源 である 否

3. ステータスコード

HTTPステータスコードはリクエストの処理結果を示します:

状态码 类别 常见状态码
2xx 成功 200 OK, 201 Created
3xx 重定向 301 Moved Permanently
4xx 客户端错误 400 Bad Request, 404 Not Found
5xx 服务器错误 500 Internal Server Error

4. データ形式

REST APIでよく使用されるデータ交換形式:

  • JSON(JavaScript Object Notation)
  • XML(eXtensible Markup Language)
  • 場合によってはYAML、CSVなどの形式も使用されます

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

1. URI設計の原則

  • リソースを表すのに動詞ではなく名詞を使う
    • 好:/users
    • 不好:/getUsers
  • 小文字とハイフン(-)を使う
  • ファイル拡張子を避ける
  • 集合を表すには複数形を使う
  • 関係を階層的に表現する:/users/{id}/orders

2. バージョン管理

URIまたはリクエストヘッダーにAPIバージョン情報を含めることを推奨します:

  • URI 路径:/v1/users
  • 请求头:Accept: application/vnd.myapi.v1+json

3. フィルタリング、ソート、ページネーション

コレクションリソースに対しては、クエリパラメータを提供する:

  • 过滤:/users?role=admin
  • 排序:/users?sort=-created_at
  • 分页:/users?page=2&limit=10

4. セキュリティ

  • 使用 HTTPS
  • 認証を実装する(OAuth2、JWT)
  • リクエスト頻度を制限する
  • 入力データを検証する

REST API 示例

ユーザー管理APIの例

实例

# 获取用户列表
GET /api/v1/users
Accept: application/json

# 创建新用户
POST /api/v1/users
Content-Type: application/json

{
  "name": "张三",
  "email": "zhangsan@example.com"
}

# 获取特定用户
GET /api/v1/users/123
Accept: application/json

# 更新用户信息
PUT /api/v1/users/123
Content-Type: application/json

{
  "name": "张三(更新)",
  "email": "new-email@example.com"
}

# 删除用户
DELETE /api/v1/users/123

响应示例

实例

// 成功响应
{
  "status": "success",
  "data": {
    "id": 123,
    "name": "张三",
    "email": "zhangsan@example.com",
    "created_at": "2023-01-01T00:00:00Z"
  }
}

// 错误响应
{
  "status": "error",
  "message": "User not found",
  "code": 404
}

REST APIをテストするためのツール

  1. Postman:強力なAPIテストツール
  2. cURL:コマンドラインツール
  3. Insomnia:軽量なAPIテストクライアント
  4. Swagger/OpenAPI:APIドキュメントおよびテストツール

cURL 示例

实例

# GET 请求
curl -X GET https://api.example.com/users/123 \
  -H "Accept: application/json"

# POST 请求
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"李四","email":"lisi@example.com"}'

REST API開発フレームワーク

プログラミング言語に応じて、REST APIの開発に使用できるさまざまなフレームワークがあります:

语言 流行框架
JavaScript Express.js, NestJS
Python Django REST Framework, Flask
Java Spring Boot
PHP Laravel, Symfony
Ruby Ruby on Rails
Go Gin, Echo

一、基本設計原則

1. 明確な命名規則を採用する

基本原则:

  • リソースを表すには(動詞ではなく)名詞を使う
  • 集合を表すには複数形を使う
  • 命名の一貫性と直感性を保つ

示例:

  • ✅ 良い設計: /users, /products, /orders

  • ❌ 良くない設計: /getUsers, /addProduct, /all-orders

扩展建议:

  • リソース間の関係を反映するために、リソースに階層的な命名を使用します:/companies/{companyId}/departments/{departmentId}/employees
  • 可読性を高めるため、複数の単語で構成されるリソース名にはハイフン(kebab-case)を使用します:/shipping-addresses而非/shippingaddresses
  • APIバージョン更新時に命名の一貫性を維持し、不要な変更によるクライアントの混乱を避けます

2. HTTPメソッドを正しく使用する

基本用法:

  • GET:リソースの読み取り(冪等)
  • POST:新しいリソースの作成
  • PUT:リソース全体の更新(冪等)
  • PATCH:リソースの部分更新
  • DELETE:リソースの削除(冪等)

示例:

GET /users          # 获取用户列表
GET /users/123      # 获取特定用户
POST /users         # 创建新用户
PUT /users/123      # 完全更新用户
PATCH /users/123    # 部分更新用户
DELETE /users/123   # 删除用户

扩展建议:

  • 冪等性の重要性を理解する:GET、PUT、DELETEは冪等操作であり、複数回呼び出しても同じ結果が得られる
  • バッチ操作では、PUTではなくPOSTの使用を検討してください。PUTは通常、クライアントがリソース識別子を明確に指定することを想定しているためです
  • PATCH 操作を設計する際は、JSON Patch (RFC 6902) または JSON Merge Patch (RFC 7386) 標準形式の使用を検討してください。
  • 複雑な操作には、リソース拡張を使用できます:POST /users/123/activate 比 POST /activateUser/123REST原則により適合する

3. 適切なHTTPステータスコードの使用

常用状态码:

  • 200 OK:リクエスト成功
  • 201 Created:リソース作成成功
  • 204 No Content:成功だが返却コンテンツなし(例:DELETE操作)
  • 400 Bad Request:クライアントエラー
  • 401 Unauthorized:未认证
  • 403 Forbidden:无权限
  • 404 Not Found:リソースが存在しない
  • 409 Conflict:リソースの競合
  • 500 Internal Server Error:服务器错误

扩展建议:

  • より詳細なステータスコードを使用してAPIの表現力を高めます:
    • 429 Too Many Requests:リクエスト頻度の制限超過
    • 405 Method Not Allowed:サポートされていないHTTPメソッド
    • 415 Unsupported Media Type:サポートされていないコンテンツタイプ
    • 422 Unprocessable Entity:语义错误
  • クライアント側の処理を簡素化するため、主要なエラーカテゴリ内で一貫性を保つことができます:クライアントエラー(4xx)とサーバーエラー(5xx)
  • ステータスコードとともに、常に意味のあるエラーメッセージとエラーコードを提供します

二、クエリとフィルタリングの設計

4. 効果的なページネーションを実装する

基本实现:

  • 使用limitとoffset或pageとsize参数
  • レスポンスにページネーションメタデータを含める

示例:

GET /products?limit=20&offset=40
GET /products?page=3&size=20

响应示例:

{
  "data": [...],
  "pagination": {
    "total": 523,
    "pages": 27,
    "current_page": 3,
    "per_page": 20,
    "next": "/products?page=4&size=20",
    "prev": "/products?page=2&size=20"
  }
}

扩展建议:

  • カーソルベースのページネーションを検討する。特に大規模なデータセットや頻繁に更新されるデータを扱う場合
  • 合理的なデフォルトのページネーション値と最大制限を設定し、過大なリクエストがパフォーマンスに影響を与えるのを防ぎます
  • ページネーションレスポンスにHATEOASリンクを提供し、クライアントのナビゲーションを容易にします(上記の例のnext/prevリンクなど)
  • 時系列データには、時間ベースのページネーションを使用できます:GET /events?since=2023-01-01T00:00:00Z&until=2023-01-31T23:59:59Z

5. 柔軟なフィルタリング、ソート、検索を提供する

基本实现:

  • クエリパラメータを使ってフィルタリングする:?status=active
  • 使用sortパラメータでソートする:?sort=created_at
  • 複数フィールドのソートと昇順/降順をサポート:?sort=price:asc,rating:desc

示例:

GET /products?category=electronics&price_min=100&price_max=500&sort=price:asc
GET /users?role=admin&search=john

扩展建议:

  • 複雑なクエリには式構文を提供する:?price=gt:100,lt:500
  • 部分一致および曖昧検索オプションを実装する:?name=like:john
  • フィールド選択をサポートし、クライアントが必要なフィールドを指定できるようにします:?fields=id,name,email
  • 特に複雑なクエリには、補足としてGraphQLエンドポイントの実装を検討します
  • よく使用されるフィルターの組み合わせについては、事前定義されたフィルターを提供します:?filter=recent可能等同于?created_after=30days&sort=created_at:desc

6. 効果的なAPIバージョン管理の実装

主要方法:

  • URLパスバージョン:/api/v1/users
  • クエリパラメータバージョン:/api/users?version=1
  • リクエストヘッダーバージョン:Accept: application/vnd.company.v1+json

扩展建议:

  • URLパスによるバージョン管理は最も直感的ですが、URIが不安定になる可能性があります
  • リクエストヘッダーによるバージョン管理はURIを安定に保ちますが、クライアントにとっては直感的ではありません
  • バージョン更新ではセマンティックバージョニングの原則に従います:
    • 後方互換性のある変更にはマイナーバージョン番号(v1.1)を使用します
    • 互換性のない変更にはメジャーバージョン番号(v2)を使用します
  • 新旧バージョン間に移行期間を設け、クライアントがスムーズに移行できるようにします
  • ドキュメントで各APIバージョンのライフサイクルステータス(開発中、安定、非推奨、停止)を明確に示します

三、レスポンス設計

7. 一貫したレスポンス構造を設計する

基本结构:

  • ラッパーオブジェクトを使用して、データとメタデータを区別します
  • エラーレスポンスの形式を一貫させる

成功レスポンスの例:

{
  "status": "success",
  "data": {
    "id": 123,
    "name": "Example Product",
    "price": 99.99
  },
  "meta": {
    "timestamp": "2023-06-15T08:30:00Z"
  }
}

エラーレスポンスの例:

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {"field": "email", "message": "Must be a valid email address"}
    ]
  },
  "meta": {
    "timestamp": "2023-06-15T08:30:00Z",
    "request_id": "req-123456"
  }
}

扩展建议:

  • エラーレスポンスに一意のエラーコードを含め、トラブルシューティングとドキュメント参照を容易にします
  • 複雑なエラー、特にフォーム検証エラーについては、構造化されたエラー詳細を提供します
  • リクエスト識別子(request_id)を含め、ログ追跡とカスタマーサポートを容易にします
  • 国際化サポートを検討し、エラーメッセージの多言語版またはエラーコードマッピングを提供します
  • エラーメッセージに機密情報や実装の詳細を漏らさないようにします

8. HATEOAS原則を実装する

基本概念:

  • HATEOAS(Hypermedia as the Engine of Application State)
  • レスポンスに関連リソースへのリンクを含め、APIを自己記述的にする

示例:

{
  "data": {
    "id": 123,
    "name": "John Doe"
  },
  "links": {
    "self": "/users/123",
    "orders": "/users/123/orders",
    "update": {"href": "/users/123", "method": "PUT"},
    "delete": {"href": "/users/123", "method": "DELETE"}
  }
}

扩展建议:

  • 標準化されたリンク関係名を使用します(HALやJSON:API仕様で定義されているものなど)
  • HTTPメソッドや必要なメディアタイプなど、リンクのコンテキスト情報を含めます
  • ユーザーの権限に基づいてリンクを動的に生成し、現在のユーザーが利用可能な操作のみを表示します
  • 入力データ形式の自己記述を提供するために、JSON Schemaの使用を検討します

9. 適切なシリアライズ形式を選択する

常用格式:

  • JSON:最も一般的で、軽量かつ解析が容易です
  • XML:より厳格だが、より冗長
  • MessagePack:バイナリ形式で、パフォーマンスが重要なシナリオに適しています

扩展建议:

  • コンテンツネゴシエーションを使用して複数の形式をサポートします:クライアントはAcceptヘッダーで期待する形式を指定する
  • JSON については、一貫した命名規則(camelCase または snake_case)に従ってください。
  • 特別なシナリオの要件を考慮する:
    • CSV形式は大量データのエクスポートに適している
    • Protocol BuffersやgRPCは、高性能なマイクロサービス間通信に適しています
    • JSON-LDはセマンティックデータが必要なシナリオに適しています
  • 異なる形式に対して一貫したデータモデルとフィールド名を提供します

四、セキュリティとパフォーマンス

10. 効果的な認証と認可の実装

常用方法:

  • APIキー:サービス間通信に適している
  • OAuth 2.0:サードパーティの認可に適しています
  • JWT(JSON Web Tokens):ステートレス認証に適する

扩展建议:

  • APIのさまざまな使用シナリオに応じて適切な認可フローを選択します:
    • ユーザーからサーバーへ:認可コードフロー
    • サーバー間:クライアント資格情報フロー
  • 最小権限の原則に従い、きめ細かい権限制御を実装します
  • APIキーのローテーションと失効メカニズムを実装する
  • 標準のOAuth 2.0スコープを使用して権限を定義します
  • 複雑な認可シナリオには、属性ベースのアクセス制御(ABAC)の実装を検討します

11. レート制限とスロットリングを実施する

基本实现:

  • リクエストレート制限を使用してAPIを保護する
  • レスポンスヘッダーに制限情報を提供する

响应头示例:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1623760800

扩展建议:

  • 多層レベルの制限を実装する:
    • IPアドレスによる制限(匿名の滥用を防ぐ)
    • ユーザー/APIキーによる制限(公平な使用)
    • リソース/エンドポイントによる制限(機密操作の保護)
  • プレミアムプランやオンデマンドの拡張オプションを提供する
  • トークンバケットまたはリーキーバケットアルゴリズムを使用して、バーストトラフィックを処理します
  • システム負荷に応じて制限を動的に調整する、適応型スロットリングを実装します
  • 重要なクライアントには優先チャネルまたは予約容量を提供します

12. キャッシュを適切に使用する

基本实现:

  • ETags と If-None-Match ヘッダーを使用する
  • 適切なCache-Controlディレクティブを設定する

示例:

Cache-Control: max-age=3600, must-revalidate
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

扩展建议:

  • リソースの種類に応じて異なるキャッシュ戦略を設定します:
    • 静的コンテンツ:長めのmax-age
    • 個人プロフィール:短いmax-ageまたはprivateディレクティブ
    • 頻繁に変化するデータ:max-ageではなくETagを使用
  • 条件付きリクエスト(If-Modified-Since、If-None-Match)を実装して帯域幅の使用を減らす
  • APIゲートウェイまたはCDNレベルでのキャッシュ実装を検討します
  • キャッシュ無効化メカニズムを提供する。特に突然更新が必要になるリソースに対して
  • キャッシュタグを使用して、きめ細かいキャッシュ管理を行います

13. コンテンツ圧縮をサポートする

基本实现:

  • gzipおよびBrotli圧縮をサポートする
  • Accept-EncodingヘッダーとContent-Encodingヘッダーを使用する

扩展建议:

  • 大きなレスポンスには自動的に圧縮を適用しますが、小さなレスポンス(<1KB)には圧縮を避けます
  • コンテンツタイプごとに圧縮レベルを最適化する
  • パフォーマンスが重要なシナリオでは、頻繁に使用されるレスポンスの事前圧縮を検討します
  • 圧縮率とCPU使用率を監視し、最適なバランスを見つけます
  • プロキシ/ゲートウェイ層で圧縮を処理し、アプリケーションサーバーの負担を軽減することを検討します

五、ドキュメントと保守性

14. 包括的なAPIドキュメントを提供する

基本实现:

  • OpenAPI/Swagger仕様を使用する
  • リクエストとレスポンスの例を含める

扩展建议:

  • 「ドキュメント・アズ・コード」アプローチを採用し、API仕様をコードと一緒にバージョン管理します
  • インタラクティブなAPIブラウザを提供し、開発者がAPIを直接テストできるようにします
  • 一般的なユースケースと統合シナリオのチュートリアルを含める
  • 各エンドポイントにサンプルコードスニペット(複数のプログラミング言語)を提供します
  • API変更ログを実装し、非推奨および新規追加された機能を明確に示します
  • ナレッジ共有を促進するために、開発者コミュニティまたはフォーラムの作成を検討します

15. モニタリングとロギング

基本实现:

  • 记录请求/响应时间
  • エラー率と使用パターンを追跡する

扩展建议:

  • W3C Trace Contextまたは同等の標準を使用して、分散トレーシングを実装します
  • 多次元の監視メトリクスを設定する:
    • エンドポイントのパフォーマンス(P95/P99レイテンシー)
    • エラー率とタイプ分布
    • クライアントの使用パターン
    • リソース消費(CPU、メモリ、帯域幅)
  • 単純なしきい値ではなく異常なパターンを検出する、インテリジェントなアラートを実装します
  • 開発者コンソールを提供し、API利用者が自分の使用統計を確認できるようにします
  • 構造化ログ形式(JSONなど)を使用して、ログの分析と検索を容易にする

16. 有用なエラーデバッグ情報の提供

基本实现:

  • 明確なエラーメッセージを提供する
  • 一意のエラーコードを含める

扩展建议:

  • 環境に応じてエラーの詳細度を調整します(本番環境では機密情報の漏えいを避ける)
  • エラーコードを詳細なトラブルシューティングガイドにマッピングする、エラーセンターを実装します
  • コンテキストに応じたヘルプリンクを提供する
  • 一般的なエラーに対して自動化された修正提案を提供する
  • 開発環境ではより詳細なスタックトレースとコンテキストを提供します
  • 重要なエラーに対して自動レポートメカニズムを実装する

六、高度な設計上の考慮事項

17. バッチ処理と非同期操作

批量处理:

  • 一括作成、更新、削除操作をサポートする
  • 部分的な成功処理オプションを提供する

一括操作の例:

POST /users/batch
{
  "operations": [
    {"method": "POST", "path": "/users", "body": {"name": "User 1"}},
    {"method": "PUT", "path": "/users/123", "body": {"name": "Updated User"}}
  ]
}

异步操作:

  • 長時間実行されるタスクには202 Acceptedを返す
  • タスクステータスエンドポイントを提供する

非同期フローの例:

POST /reports/generate
Response: 202 Accepted
Location: /tasks/abc-123

GET /tasks/abc-123
Response: {"status": "processing", "progress": 45, "eta": "30s"}

GET /tasks/abc-123
Response: {"status": "completed", "result": "/reports/xyz-789"}

扩展建议:

  • webhookベースの非同期通知を実装し、タスク完了時にクライアントをコールバックします
  • バッチ操作には原子性オプション(すべて成功またはすべて失敗)を提供します
  • バッチ操作における依存関係(ある操作が別の操作の結果に依存する)をサポートする
  • タスクの優先順位メカニズムとキャンセル機能を提供する
  • タスクの再試行戦略と障害処理メカニズムを実装します

18. API設計の進化を考慮する

基本原则:

  • 変更ではなく追加を使用する
  • 削除を避け、非推奨にしてから削除する
  • 後方互換性を維持する

扩展建议:

  • 明確なAPIライフサイクルポリシーを策定します:
    • プレビュー/Alpha/Beta版の安定性の期待値
    • 非推奨期間(通常は少なくとも6〜12か月)
    • 長期サポート(LTS)バージョンのメンテナンス期間
  • フィーチャーフラグを使用して新機能を段階的に展開します
  • API使用分析を実装し、どのエンドポイントと機能がもはや使用されていないかを把握します
  • 移行ツールと例を提供し、クライアントが新バージョンへ移行しやすくする
  • カスタムフィールドやメタデータのサポートなど、設計時の拡張ポイントを検討します

7. 業界固有の最適化と新トレンド

モバイルアプリAPIの最適化

  • GraphQLエンドポイントを実装し、モバイルクライアントが必要なデータを正確にリクエストできるようにします
  • 部分レスポンスをサポートして帯域幅の使用を削減する:?fields=id,name,thumbnail
  • ネットワークラウンドトリップを減らすために、バッチプリロードAPIを提供します
  • デバイスの能力とネットワーク条件に応じてレスポンスサイズを調整する、レスポンシブデザインを検討します
  • 変更データのみを転送する、増分同期メカニズムを実装します

モノのインターネット(IoT)APIの考慮事項

  • 軽量プロトコル(MQTTやCoAPなど)をサポートします
  • デバイス状態モデルと双方向通信を実装する
  • 带宽使用を最適化し、バイナリ形式と圧縮を使用する
  • オフライン操作と競合解決戦略を設計する
  • デバイス管理とファームウェア更新APIを提供する

APIファースト開発アプローチ

  • コードファースト(Code-First)ではなくデザインファースト(Design-First)アプローチを採用する
  • APIモデル駆動開発プロセスを使用する(例:OpenAPI仕様からコードを生成する)
  • 一貫性と品質を確保するため、API設計レビュープロセスを実施する
  • APIスタイルガイドとベストプラクティスドキュメントを確立する
  • 契約テストを使用して実装が仕様に適合していることを確認する

八、总结

適切に設計されたREST APIは、可用性、パフォーマンス、セキュリティ、保守性など、さまざまな要素のバランスを慎重に取る必要があります。これらのベストプラクティスに従うことで、開発チームはRESTの原則を満たしつつ、現代のアプリケーションのニーズを満たすAPIを作成できます。鍵となるのは、一貫性と直感性を維持し、常にAPIコンシューマーの視点で考えることです。APIエコノミーの発展に伴い、高品質なAPI設計は組織の成功における重要な要素となるでしょう。

九、関連資料

  1. RESTful Web APIs (Leonard Richardson, Mike Amundsen)
  2. API設計パターン (JJ Geewax)
  3. Web API設計:モダンアプリケーションを構築するためのベストプラクティス(Arnaud Lauret)
  4. REST APIセキュリティガイド (OWASP)
  5. リチャードソン成熟度モデル:REST APIの進化レベルを理解する