Api Integration

API Integration Auto-Generation

Engineering Delivery Boundary

Follow [Engineering Boundary Protocol](../../../codex-templates/engineering-boundary-protocol.md).

1. Project first: inspect existing framework, router, state management, component library, styling, API client, and test stack before writing code; inherit by default.
2. Design-system first: existing design system, component library, and brand rules override visual_policy unless the user explicitly asks to change them.
3. Write scope: declare target directories and files before implementation; do not overwrite unrelated user code.
4. Responsive acceptance: check desktop/mobile layout, text overflow, cramped controls, nested cards, accessibility basics, and design-token consistency.
5. Verification record: report created/modified files, checks run, checks that could not run, and residual risks.

Code Write Boundary

Follow [Engineering Boundary Protocol](../../../codex-templates/engineering-boundary-protocol.md).

1. Scan first: identify existing HTTP client, API directory structure, authentication mechanism, and data fetching library before writing code; inherit by default.
2. Target scope: declare target directories and files before implementation; generated code must stay inside {project_dir}/src/api/ unless integration files are explicitly required.
3. No overwrite: preserve existing API functions, type definitions, and mock data unless the user explicitly asks for replacement; when replacing page-builder fallback, maintain function signatures.
4. Type safety: all request parameters and responses must have TypeScript types derived from API contracts; zero any types.
5. Fallback replacement: when replacing page-builder fallback data layer, preserve type definitions (types.ts), only replace data fetch functions and mock data.
6. Implementation report: list created/modified files, skipped files, checks run, failed checks, and residual risks.

Core Principles

1. Contract-Driven -- API client code auto-generated from contracts, no hand-written request functions. When contracts are missing, infer from page data flows, but inference results must be human-confirmed
2. Type Safety -- Request parameters and response types 100% derived from contracts, zero any types
3. Defensive Programming -- Every API call has error handling, timeout, and retry; error handling strategy defined in layers
4. Built-in Authentication -- Token management, refresh, expiration handling as infrastructure, never missed
5. Developer Experience -- Mock data auto-generated, frontend and backend can develop in parallel, one-click switch between mock and real APIs

Interaction Mode

AI->Human AI suggests, human confirms

Input

| Input Item | Type | Required | Source | Description | |--------|------|------|------|------| | API Contract | YAML/JSON | O | output/backend-api-design/api-design-spec/openapi.yaml | OpenAPI 3.0 specification (infer from page data flows when missing) | | Authentication Scheme | JSON | O | output/backend-api-design/api-design-spec/auth-scheme.json | Backend API authentication design (JWT/OAuth2/SSO scheme, permission model, session management), takes priority over PRD non-functional requirements | | Security Policy | JSON | O | output/backend-api-design/api-design-spec/security-policy.json | Backend API security policy (rate limiting rules, CORS policy, data masking rules), for frontend error handling and security policy alignment | | Page Data Flows | JSON | Yes | output/ui-frontend/page-builder/pages.json | Page data fetching requirements | | Target Framework | string | Yes | Passed from upstream orchestrator | React/Vue/Svelte | | Target Language | string | O | Passed from upstream orchestrator (default zh-CN) | Target interface language, affects mock data and error message language | | project_dir | string | Yes | Passed from upstream orchestrator | Project root directory absolute path | | Auth Scheme | string | O | PRD non-functional requirements / User provided | JWT/OAuth2/Cookie/ApiKey (default JWT), used when auth-scheme.json is unavailable |

Execution Steps

Step 1: API Contract Parsing and Endpoint Planning

1a. Contract Parsing

If API contract input exists:

1. Parse OpenAPI/Swagger specification, extract all endpoints (method/path/parameters/requestBody/responses)
2. Extract authentication schemes (security schemes)
3. Extract common error code definitions
4. Mark deprecated endpoints

If API contract is missing:

1. Infer API endpoints from pages.json data_flow fields
2. Inference rule: each data_flow source corresponds to one API endpoint
3. Inferred endpoints marked with inferred: true
4. Generate inference report, requires human confirmation

1b. Endpoint Classification and Directory Planning

| Classification Rule | Directory Structure | Example | |---------|---------|------| | By domain module | src/api/{module}/ | src/api/auth/, src/api/user/, src/api/product/ | | Common endpoints | src/api/shared/ | Health check, config endpoints | | Endpoints redirect to login page

• Concurrent requests queue while refresh is in progress

Step 2: API Client Code Generation

2a. Type Definition Generation

Derive TypeScript types from contract schema:

type {Endpoint}Request = { /* derived from requestBody */ }
type {Endpoint}Response = { /* derived from 200 response schema */ }
type {Endpoint}Error = { /* derived from 4xx/5xx response schema */ }

type ApiResponse = { code: number; data: T; message: string }
type PaginatedResponse = { items: T[]; total: number; page: number; page_size: number }

2b. Request Function Generation

Generate one request function per endpoint:

export async function {endpointName}(params: {Endpoint}Request, config?: RequestConfig): Promise {
  return request.{method}('{path}', params, config)
}

Generation rules:

• GET request parameters mapped as query parameters
• POST/PUT/PATCH request parameters mapped as request body
• Path parameters (e.g. /users/{id}) extracted from params
• Each function includes JSDoc comments (extracted from contract description/summary)

2c. Request Layer Infrastructure

| Infrastructure | Implementation Content | |---------|---------| | HTTP Client | Axios instance (React/Vue) or fetch wrapper (Svelte) | | Request Interceptor | Token injection + request ID + timestamp + request body serialization | | Response Interceptor | Unified error handling + token expiration auto-refresh + response unwrapping | | Error Handling | Network error/timeout(10s)/business error/auth expiration layered handling | | Retry Strategy | Network errors and 5xx retry 2 times, exponential backoff (1s/2s) | | Cancellation Mechanism | AbortController wrapper, auto-cancel on page unmount | | Request Deduplication | Merge concurrent requests with same URL+parameters |

2d. Error Handling Strategy

| Error Type | Handling Method | User Feedback | |---------|---------|---------| | Network error | Retry 2 times -> prompt network exception | "Network connection error, please check your network and retry" | | Timeout (>10s) | Retry 1 time -> prompt response timeout | "Request timed out, please try again later" | | 401 Unauthorized | Attempt token refresh -> redirect to login | Auto-redirect to login page | | 403 Forbidden | Prompt no permission | "You do not have permission to perform this action" | | 404 Not Found | Prompt resource not found | "Requested resource not found" | | 422 Validation Failed | Extract field errors | Display specific field error messages | | 429 Rate Limited | Wait then retry | "Too many requests, please try again later" | | 5xx Server Error | Retry 2 times -> prompt server exception | "Server error, please try again later" |

Step 3: Mock Data and Parallel Development

3a. Mock Data Generation

Generate mock data from contract response schema:

• String type: Infer content from field name (name->"John Doe", email->"test@example.com")
• Number type: Generate based on range constraints, use reasonable defaults when no constraints
• Array type: Generate 3-5 records
• Nested objects: Generate recursively
• Enum type: Randomly select one value
• When target language != en-US, mock data uses target language content

3b. Mock Switch Mechanism

export const useMock = import.meta.env.VITE_API_MOCK === 'true'

export async function getUser(id: string) {
  if (useMock) return mockData.user
  return request.get(`/users/${id}`)
}

3c. MSW Integration (Recommended)

Generate MSW (Mock Service Worker) handlers:

• One handler per endpoint
• Support request parameter matching
• Support delay simulation (200-500ms random delay)
• Support error scenario simulation (5% probability of returning 500 error)

Step 4: Data Layer Integration and Cache Strategy

4a. Data Preloading Configuration

| Framework | Solution | Configuration | |------|------|------| | React | React Query (TanStack Query) | staleTime/cacheTime/refetchOnWindowFocus | | Vue | Vue Query (TanStack Query) | staleTime/cacheTime/refetchOnWindowFocus | | Svelte | svelte-query | staleTime/cacheTime/refetchOnWindowFocus |

4b. Cache Strategy

| Data Type | staleTime | cacheTime | Refetch Strategy | |---------|-----------|-----------|------------| | User info | 5min | 30min | Window focus | | List data | 2min | 10min | Window focus | | Detail data | 10min | 30min | No auto-refresh | | Config data | 30min | 60min | No auto-refresh | | Realtime data | 0 | 5min | Polling (5s) |

4c. Optimistic Update Configuration

Generate optimistic update configuration for write operations (POST/PUT/PATCH):

• Update operations: Immediately update cache, rollback on failure
• Delete operations: Immediately remove from cache, restore on failure
• Create operations: Immediately add to cache (temporary ID), replace with real ID on success

4d. Replace page-builder Fallback Data Layer

When api-integration executes, replace page-builder generated fallback data layer:

1. Locate all files annotated with @api-integration
2. Replace fallback functions with api-integration generated request functions
3. Keep function signatures consistent (page-builder fallback signatures aligned with api-integration request function signatures)
4. Delete no-longer-needed mock data files
5. Verify page functionality after replacement

Output

Code File Output: {project_dir}/src/api/ (API client, type definitions, mock data directly written to project directory)

Metadata Output: output/ui-frontend-integration/api-integration/

Output Files: api-integration.json

Output Schema:

{
  "type": "object",
  "required": ["endpoints", "types", "mock_data", "auth_config", "cache_config", "error_handling", "project_dir"],
  "properties": {
    "endpoints": {
      "type": "array",
      "description": "API endpoint list",
      "items": {
        "type": "object",
        "properties": {
          "name": {"type": "string", "description": "Function name"},
          "method": {"type": "string", "enum": ["GET","POST","PUT","PATCH","DELETE"]},
          "path": {"type": "string", "description": "API path"},
          "request_type": {"type": "string", "description": "Request type name"},
          "response_type": {"type": "string", "description": "Response type name"},
          "module": {"type": "string", "description": "Module"},
          "inferred": {"type": "boolean", "description": "Whether inferred endpoint"},
          "deprecated": {"type": "boolean", "description": "Whether deprecated"}
        }
      }
    },
    "types": {
      "type": "array",
      "description": "TypeScript type definition file list",
      "items": {
        "type": "object",
        "properties": {
          "file_path": {"type": "string", "description": "Type file path"},
          "type_count": {"type": "number", "description": "Number of defined types"},
          "endpoints_covered": {"type": "array", "description": "Covered endpoint list"}
        }
      }
    },
    "mock_data": {
      "type": "array",
      "description": "Mock data file list",
      "items": {
        "type": "object",
        "properties": {
          "file_path": {"type": "string", "description": "Mock data file path"},
          "endpoint": {"type": "string", "description": "Corresponding endpoint"},
          "record_count": {"type": "number", "description": "Mock data record count"}
        }
      }
    },
    "auth_config": {
      "type": "object",
      "description": "Authentication configuration",
      "properties": {
        "type": {"type": "string", "enum": ["JWT","OAuth2","Cookie","ApiKey","None"]},
        "token_storage": {"type": "string", "description": "Token storage method"},
        "refresh_enabled": {"type": "boolean", "description": "Whether auto-refresh is enabled"},
        "login_redirect": {"type": "string", "description": "Unauthorized redirect path"}
      }
    },
    "cache_config": {
      "type": "object",
      "description": "Cache strategy configuration",
      "properties": {
        "library": {"type": "string", "description": "Data request library"},
        "strategies": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "data_type": {"type": "string", "description": "Data type (user_info/list_data/detail_data/config_data/realtime_data)"},
              "stale_time": {"type": "string", "description": "Data freshness time"},
              "cache_time": {"type": "string", "description": "Cache retention time"},
              "refetch_strategy": {"type": "string", "description": "Refetch strategy (window_focus/polling/none)"}
            }
          }
        }
      }
    },
    "error_handling": {
      "type": "object",
      "description": "Error handling configuration",
      "properties": {
        "timeout_ms": {"type": "number", "description": "Request timeout (ms)"},
        "retry_count": {"type": "number", "description": "Retry count"},
        "retry_delay_ms": {"type": "number", "description": "Retry delay (ms)"},
        "error_codes_mapped": {"type": "number", "description": "Number of mapped error codes"},
        "error_strategies": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "error_type": {"type": "string", "description": "Error type (network/timeout/401/403/404/422/429/5xx)"},
              "handling": {"type": "string", "description": "Handling method"},
              "user_feedback": {"type": "string", "description": "User feedback text"}
            }
          }
        }
      }
    },
    "project_dir": {"type": "string", "description": "Project root directory path"}
  }
}

Decision Rules

| Condition | Decision | |------|------| | Target framework = React | Use React Query + axios | | Target framework = Vue | Use Vue Query + axios | | Target framework = Svelte | Use svelte-query + fetch wrapper | | API endpoints >20 | Split files by domain module | | Has pagination interfaces | Generate generic pagination Hook | | Has file upload interfaces | Generate progress callback wrapper | | Target language != en-US | Mock data uses target language content | | Auth scheme = JWT | Auto-generate token refresh interceptor | | Auth scheme missing | Default JWT, mark as "auth scheme pending confirmation" | | Inferred endpoints >50% | Mark as "high inference ratio, recommend supplementing API contract" |

Quality Checks

P0 (Must pass, blocks output if not):

• [ ] 100% of API endpoints have corresponding request functions
• [ ] 100% of request parameters and responses have TypeScript types (zero any)
• [ ] Authentication scheme configured (token injection + refresh + expiration handling)
• [ ] Interceptor configuration complete (token injection + error handling + response unwrapping)
• [ ] API code quality audit score >=70 (called by orchestrato

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: LuckyOneTwoThree
• Source: LuckyOneTwoThree/vibe-skill
• License: MIT
• Homepage: https://luckyonetwothree.github.io/all-skill-html/

Install and usage instructions live in the source repository linked above.