phase-4-api（phase 4 API 文档）

Phase 4: API Design/Implementation + Zero Script QA

Backend API implementation and script-free QA

Purpose

Implement backend APIs that can store and retrieve data. Validate with structured logs instead of test scripts.

What to Do in This Phase

1. API Design: Define endpoints, requests/responses
2. API Implementation: Write actual backend code
3. Zero Script QA: Log-based validation

Deliverables

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

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

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

PDCA Application

• Plan: Define required API list
• Design: Design endpoints, requests/responses
• Do: Implement APIs
• Check: Validate with Zero Script QA
• Act: Fix bugs and proceed to Phase 5

Level-wise Application

Dynamic Level: bkend.ai BaaS API Implementation

Step 1: MCP Setup

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

Step 2: Table Design (via MCP tools)

Natural language request: "Create a users table with name(required), email(required, unique), age fields" -> MCP backend_table_create auto-invoked

Step 3: Service API Integration

Required Headers: x-project-id, x-environment, Authorization

Step 4: Auth Implementation

Reference MCP tools 3_howto_implement_auth and 6_code_examples_auth

Step 5: Zero Script QA

• Check bkend REST API call logs in browser DevTools Network tab
• Verify API behavior via response code/body

What is Zero Script QA?

Instead of writing test scripts, validate with structured debug logs

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

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

RESTful API Principles

What is REST?

REpresentational State Transfer - an architecture style for designing web services.

6 Core Principles

Uniform Interface Details

The core of RESTful APIs is a uniform interface.

1. Resource-Based URLs

✅ 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 Method Meanings

Idempotent: Same result even if requested multiple times Safe: Doesn't change server state

3. HTTP Status Codes

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. Consistent Response Format

// Success response
{
  "data": {
    "id": 123,
    "email": "user@example.com",
    "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 Design Rules

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 Documentation Tools

API Design Checklist

• RESTful Principles Compliance

- Resource-based URLs (nouns, plural) - Appropriate HTTP methods - Correct status codes

• Unified error response format
• Authentication/authorization method defined
• Pagination method defined
• Versioning method (optional)

Templates

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

Next Phase

Phase 5: Design System → APIs are ready, now build UI components