phase-4-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Phase 4: API Design/Implementation + Zero Script QA

第4阶段：API设计/实现 + Zero Script QA

Backend API implementation and script-free QA

后端API实现与无脚本QA

Purpose

目标

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

实现可存储和检索数据的后端API，通过结构化日志而非测试脚本进行验证。

What to Do in This Phase

本阶段需完成的工作

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

API设计：定义端点、请求/响应格式
API实现：编写实际后端代码
Zero Script QA：基于日志的验证

Deliverables

交付物

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

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

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

docs/02-design/
└── api-spec.md             # API规格说明

src/api/                    # API实现代码
├── routes/
├── controllers/
└── services/

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

PDCA Application

PDCA循环应用

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

计划（Plan）：定义所需API列表
设计（Design）：设计端点、请求/响应格式
执行（Do）：实现API
检查（Check）：使用Zero Script QA进行验证
处理（Act）：修复问题并进入第5阶段

Level-wise Application

分级别应用

Level	Application Method
Starter	Skip this Phase (no API)
Dynamic	Use bkend.ai BaaS (see below)
Enterprise	Implement APIs directly

级别	应用方式
入门级（Starter）	跳过本阶段（无API需求）
动态级（Dynamic）	使用bkend.ai BaaS（见下文）
企业级（Enterprise）	直接实现API

Dynamic Level: bkend.ai BaaS API Implementation

动态级：bkend.ai BaaS API实现

Step 1: MCP Setup

步骤1：MCP设置

bash

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

bash

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

Step 2: Table Design (via MCP tools)

步骤2：表设计（通过MCP工具）

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

backend_table_create

auto-invoked

自然语言请求："创建一个users表，包含必填字段name、必填且唯一的email字段，以及age字段" -> 自动调用MCP的

backend_table_create

功能

Step 3: Service API Integration

步骤3：服务API集成

Method	Endpoint	Description
GET	/v1/data/{table}	List (filter, sort, page)
POST	/v1/data/{table}	Create data
GET	/v1/data/{table}/{id}	Get single
PATCH	/v1/data/{table}/{id}	Partial update
DELETE	/v1/data/{table}/{id}	Delete

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

方法	端点	描述
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

Step 4: Auth Implementation

步骤4：认证实现

Reference MCP tools

3_howto_implement_auth

and

6_code_examples_auth

参考MCP工具的

3_howto_implement_auth

和

6_code_examples_auth

Step 5: Zero Script QA

步骤5：Zero Script QA

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

在浏览器开发者工具的Network标签中查看bkend REST API调用日志
通过响应码/响应体验证API行为

What is Zero Script QA?

什么是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

无需编写测试脚本，通过结构化调试日志完成验证

[API] POST /api/users
[INPUT] { "email": "test@test.com", "name": "Test" }
[PROCESS] 邮箱重复检查 → 通过
[PROCESS] 密码哈希 → 完成
[PROCESS] 数据库存储 → 成功
[OUTPUT] { "id": 1, "email": "test@test.com" }
[RESULT] ✅ 成功

优势：
- 节省测试代码编写时间
- 直观查看实际运行行为
- 调试更便捷

RESTful API Principles

RESTful API原则

What is REST?

什么是REST？

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

REpresentational State Transfer（表述性状态转移）- 一种用于设计Web服务的架构风格。

6 Core Principles

6大核心原则

Principle	Description	Example
1. Client-Server	Separation of concerns between client and server	UI ↔ Data storage separated
2. Stateless	Each request is independent, server doesn't store client state	Auth token included with each request
3. Cacheable	Responses must indicate if cacheable	`Cache-Control` header
4. Uniform Interface	Interact through consistent interface	Detailed below
5. Layered System	Allow layered system architecture	Load balancer, proxy
6. Code on Demand	(Optional) Server can send code to client	JavaScript delivery

原则	描述	示例
1. 客户端-服务器分离	客户端与服务器关注点分离	UI与数据存储分离
2. 无状态	每个请求独立，服务器不存储客户端状态	每个请求都包含认证令牌
3. 可缓存	响应需标明是否可缓存	`Cache-Control` 请求头
4. 统一接口	通过一致的接口进行交互	详情见下文
5. 分层系统	支持分层系统架构	负载均衡器、代理服务器
6. 按需代码	（可选）服务器可向客户端发送代码	交付JavaScript代码

Uniform Interface Details

统一接口详情

The core of RESTful APIs is a uniform interface.

RESTful API的核心是统一接口。

1. Resource-Based URLs

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

✅ 规范写法（名词、复数）
GET    /users          # 用户列表
GET    /users/123      # 特定用户
POST   /users          # 创建用户
PUT    /users/123      # 更新用户
DELETE /users/123      # 删除用户

❌ 不规范写法（使用动词）
GET    /getUsers
POST   /createUser
POST   /deleteUser/123

2. HTTP Method Meanings

2. HTTP方法的含义

Method	Purpose	Idempotent	Safe
`GET`	Read	✅	✅
`POST`	Create	❌	❌
`PUT`	Full update	✅	❌
`PATCH`	Partial update	❌	❌
`DELETE`	Delete	✅	❌

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

方法	用途	幂等性	安全性
`GET`	读取数据	✅	✅
`POST`	创建数据	❌	❌
`PUT`	全量更新	✅	❌
`PATCH`	部分更新	❌	❌
`DELETE`	删除数据	✅	❌

幂等性：多次请求结果一致 安全性：不会改变服务器状态

3. HTTP Status Codes

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

2xx 成功
├── 200 OK              # 成功（读取、更新操作）
├── 201 Created         # 创建成功
└── 204 No Content      # 成功但无响应体（删除操作）

4xx 客户端错误
├── 400 Bad Request     # 请求无效（验证失败）
├── 401 Unauthorized    # 需要认证
├── 403 Forbidden       # 无权限
├── 404 Not Found       # 资源不存在
└── 409 Conflict        # 冲突（如重复数据）

5xx 服务器错误
├── 500 Internal Error  # 服务器内部错误
└── 503 Service Unavailable  # 服务不可用

4. Consistent Response Format

4. 一致的响应格式

json

// 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
  }
}

json

// 成功响应
{
  "data": {
    "id": 123,
    "email": "user@example.com",
    "name": "John Doe"
  },
  "meta": {
    "timestamp": "2026-01-08T10:00:00Z"
  }
}

// 错误响应
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "邮箱格式无效。",
    "details": [
      { "field": "email", "message": "请输入有效的邮箱地址" }
    ]
  }
}

// 列表响应（分页）
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

URL Design Rules

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

1. 使用小写字母
   ✅ /users/123/orders
   ❌ /Users/123/Orders

2. 使用连字符(-)，避免下划线(_)
   ✅ /user-profiles
   ❌ /user_profiles

3. 体现层级关系
   ✅ /users/123/orders/456

4. 通过查询参数进行过滤
   ✅ /users?status=active&sort=created_at
   ❌ /users/active/sort/created_at

5. 版本管理
   ✅ /api/v1/users
   ✅ 请求头：Accept: application/vnd.api+json;version=1

API Documentation Tools

API文档工具

Tool	Features
OpenAPI (Swagger)	Industry standard, auto documentation
Postman	Testing + documentation
Insomnia	Lightweight API client

工具	特性
OpenAPI (Swagger)	行业标准，自动生成文档
Postman	测试+文档生成
Insomnia	轻量API客户端

API Design Checklist

API设计检查清单

Templates

模板

templates/pipeline/phase-4-api.template.md

templates/pipeline/zero-script-qa.template.md

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

第5阶段：设计系统 → API已就绪，开始构建UI组件