phase-4-api

フェーズ 4：API の設計・実装＋スクリプト不要の QA

バックエンド API の実装とスクリプトを使わない QA

目的

データを保存および取得できるバックエンド API を実装します。テストスクリプトの代わりに、構造化ログを使って検証します。

このフェーズで行うこと

1. API 設計：エンドポイントとリクエスト／レスポンスを定義します
2. API 実装：実際のバックエンドコードを作成します
3. スクリプト不要の QA：ログに基づいて検証します

成果物

docs/02-design/
└── api-spec.md             # API specification

src/api/                    # API implementation
├── routes/
├── controllers/
└── services/

docs/03-analysis/
└── api-qa.md               # QA results

PDCA の適用

• Plan：必要な API の一覧を定義します
• Design：エンドポイントとリクエスト／レスポンスを設計します
• Do：API を実装します
• Check：スクリプト不要の QA で検証します
• Act：バグを修正し、フェーズ 5 に進みます

レベル別の適用

レベル	適用方法
Starter	このフェーズをスキップします（API なし）
Dynamic	bkend.ai BaaS を使用します（以下を参照）
Enterprise	API を直接実装します

Dynamic レベル：bkend.ai BaaS API の実装

ステップ 1：MCP のセットアップ

claude mcp add bkend --transport http https://api.bkend.ai/mcp

ステップ 2：テーブル設計（MCP ツール経由）

自然言語でのリクエスト：「name（必須）、email（必須、一意）、age フィールドを持つ users テーブルを作成してください」 -> MCP backend_table_create が自動的に呼び出されます

ステップ 3：サービス API の統合

メソッド	エンドポイント	説明
GET	/v1/data/{table}	一覧表示（フィルター、並べ替え、ページ指定）
POST	/v1/data/{table}	データを作成
GET	/v1/data/{table}/{id}	単一データを取得
PATCH	/v1/data/{table}/{id}	部分更新
DELETE	/v1/data/{table}/{id}	削除

必須ヘッダー：x-project-id、x-environment、Authorization

ステップ 4：認証の実装

MCP ツール 3_howto_implement_auth および 6_code_examples_auth を参照してください

ステップ 5：スクリプト不要の QA

• ブラウザーの DevTools の Network タブで、bkend REST API 呼び出しのログを確認します
• レスポンスコード／本文で API の動作を検証します

スクリプト不要の QA とは？

Instead of writing test scripts, validate with structured debug logs

[API] POST /api/users
[INPUT] { "email": "[email protected]", "name": "Test" }
[PROCESS] Email duplicate check → Passed
[PROCESS] Password hash → Complete
[PROCESS] DB save → Success
[OUTPUT] { "id": 1, "email": "[email protected]" }
[RESULT] ✅ Success

Advantages:
- Save test code writing time
- See actual behavior with your eyes
- Easy debugging

RESTful API の原則

REST とは？

REpresentational State Transfer（表現状態転送）—Web サービスを設計するためのアーキテクチャスタイルです。

6 つの基本原則

原則	説明	例
1. クライアント・サーバー	クライアントとサーバーの責務を分離します	UI ↔ データストレージを分離
2. ステートレス	各リクエストは独立しており、サーバーはクライアントの状態を保存しません	リクエストごとに認証トークンを含める
3. キャッシュ可能	レスポンスでキャッシュ可能かどうかを示す必要があります	Cache-Control ヘッダー
4. 統一インターフェース	一貫したインターフェースを通じてやり取りします	以下で詳しく説明
5. 階層化システム	階層化されたシステムアーキテクチャを使用できます	ロードバランサー、プロキシ
6. コードオンデマンド	（任意）サーバーはクライアントにコードを送信できます	JavaScript の配信

統一インターフェースの詳細

RESTful API の中核となるのは、統一インターフェースです。

1. リソースベースの URL

✅ Good (nouns, plural)
GET    /users          # User list
GET    /users/123      # Specific user
POST   /users          # Create user
PUT    /users/123      # Update user
DELETE /users/123      # Delete user

❌ Bad (using verbs)
GET    /getUsers
POST   /createUser
POST   /deleteUser/123

2. HTTP メソッドの意味

メソッド	目的	冪等性	安全性
GET	読み取り	✅	✅
POST	作成	❌	❌
PUT	全体更新	✅	❌
PATCH	部分更新	❌	❌
DELETE	削除	✅	❌

冪等性：複数回リクエストしても同じ結果になること 安全性：サーバーの状態を変更しないこと

3. HTTP ステータスコード

2xx Success
├── 200 OK              # Success (read, update)
├── 201 Created         # Creation success
└── 204 No Content      # Success but no response body (delete)

4xx Client Error
├── 400 Bad Request     # Invalid request (validation failure)
├── 401 Unauthorized    # Authentication required
├── 403 Forbidden       # No permission
├── 404 Not Found       # Resource not found
└── 409 Conflict        # Conflict (duplicate, etc.)

5xx Server Error
├── 500 Internal Error  # Internal server error
└── 503 Service Unavailable  # Service unavailable

4. 一貫したレスポンス形式

// Success response
{
  "data": {
    "id": 123,
    "email": "[email protected]",
    "name": "John Doe"
  },
  "meta": {
    "timestamp": "2026-01-08T10:00:00Z"
  }
}

// Error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email format is invalid.",
    "details": [
      { "field": "email", "message": "Please enter a valid email" }
    ]
  }
}

// List response (pagination)
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

URL 設計ルール

1. Use lowercase
   ✅ /users/123/orders
   ❌ /Users/123/Orders

2. Use hyphens (-), avoid underscores (_)
   ✅ /user-profiles
   ❌ /user_profiles

3. Express hierarchical relationships
   ✅ /users/123/orders/456

4. Filtering via query parameters
   ✅ /users?status=active&sort=created_at
   ❌ /users/active/sort/created_at

5. Version management
   ✅ /api/v1/users
   ✅ Header: Accept: application/vnd.api+json;version=1

API ドキュメントツール

ツール	特徴
OpenAPI (Swagger)	業界標準、自動ドキュメント生成
Postman	テスト＋ドキュメント
Insomnia	軽量な API クライアント

---

API 設計チェックリスト

• RESTful 原則への準拠
  • リソースベースの URL（名詞、複数形）
  • 適切な HTTP メソッド
  • 正しいステータスコード
• 統一されたエラーレスポンス形式
• 認証／認可方式の定義
• ページネーション方式の定義
• バージョニング方式（任意）

テンプレート

• templates/pipeline/phase-4-api.template.md
• templates/pipeline/zero-script-qa.template.md

次のフェーズ

フェーズ 5：デザインシステム → API の準備ができたので、UI コンポーネントを構築します