/phase-4-api

name: phase-4-api
context: fork
background: false
classification: capability
classification-reason: Pattern guidance may overlap with model's built-in knowledge as it improves
deprecation-risk: medium
effort: high
user-invocable: false
description: |
  Design and implement backend APIs with Zero Script QA validation.
  Triggers: API design, REST API, backend, endpoint
agent: bkit:qa-monitor
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
next-skill: phase-5-design-system
pdca-phase: do
task-template: "[Phase-4] {feature}"

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

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

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

| 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

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?

**RE**presentational **S**tate **T**ransfer - an architecture style for designing web services.

6 Core Principles

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

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

| 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

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 (_)
   ✅ /use