API Integration

Overview

Skill nay tu dong hoa qua trinh tich hop API tu backend (Agent-skill-api) vao frontend (Agent-skill-web). No thuc hien:

1. •Nghien cuu API: Doc va hieu API endpoint
2. •Phan tich API: Xac dinh request/response structure
3. •Ghep API: Tao service methods trong frontend
4. •Dong bo: Cap nhat types khi backend thay doi

Khi Nao Su Dung Skill Nay

1. Nghien Cuu API

• •Khi can hieu API endpoint hoat dong nhu the nao
• •Khi can biet API yeu cau nhung gi (params, body, headers)
• •Khi can biet API tra ve gi

2. Phan Tich API

• •Khi can tao tai lieu cho API
• •Khi can hieu cau truc data chi tiet
• •Khi can validation rules cua request

3. Ghep API

• •Khi can tao service method moi trong frontend
• •Khi can ket noi frontend component voi backend API
• •Khi can tao types cho API response

4. Dong Bo Cau Truc Data

• •Khi backend API da thay doi nhung frontend chua cap nhat
• •Khi types frontend khong khop voi response backend
• •Khi can cap nhat interface sau khi backend sua doi

Workflow Tong Quan

[Input: File API Backend]
         |
         v
[PHASE 1: Nghien Cuu & Phan Tich API]
- Doc file route.ts
- Xac dinh request params/body
- Xac dinh response structure
- Tao tai lieu API
         |
         v
[PHASE 2: Ghep API vao Frontend]
- Them endpoint constant
- Tao/cap nhat types
- Tao/cap nhat service method
         |
         v
[PHASE 3: Dong Bo & Kiem Tra]
- So sanh types backend vs frontend
- Cap nhat neu khong khop
- Xac nhan dong bo thanh cong
         |
         v
[Output: Frontend san sang su dung API]

PHASE 1: Nghien Cuu & Phan Tich API

Buoc 1.1: Doc File API Backend

Doc file API backend duoc cung cap (thuong la route.ts).

Tim cac thanh phan:

• •JSDoc Comment: Mo ta API, parameters, response
• •Zod Schema: Validation rules cho request
• •Handler Function: GET, POST, PATCH, DELETE
• •Response Calls: successResponse, errorResponse

Buoc 1.2: Phan Tich Request

Trich xuat thong tin request:

Request Parameters:
- Query params: Tim trong searchParams hoac Zod schema
- Body: Tim trong request.json() hoac Zod schema
- Path params: Tim trong ten file [param] va function params
- Headers: Tim request.headers.get()

Ghi chu:

• •Truong bat buoc: Khong co .optional() trong Zod
• •Truong tuy chon: Co .optional() hoac .default()
• •Validation: Tim .min(), .max(), .email(), etc.

Buoc 1.3: Phan Tich Response

Tim cau truc response trong:

• •successResponse(data, message) -> Lay cau truc data
• •return NextResponse.json() -> Lay object tra ve
• •PayloadCMS queries -> Tim collection va depth

Xac dinh cac truong response:

• •Primitive: string, number, boolean
• •Object: Nested structure
• •Array: Item type
• •Relationship: ID string hoac populated object

Buoc 1.4: Tao Tai Lieu API

Tao thu muc va file:

docs/api/{feature-name}/
├── index.md          # Tai lieu chinh
└── examples/         # Vi du request/response (tuy chon)

Su dung template tu assets/api-doc-template.md.

PHASE 2: Ghep API vao Frontend

Buoc 2.1: Them Endpoint Constant

Tim file Agent-skill-web/src/api/endpoints.ts.

Them endpoint moi:

{FEATURE}: {
  {ACTION}: '/api/v1/{path}',
}

Buoc 2.2: Tao/Cap Nhat Types

Tim trong frontend:

Agent-skill-web/src/types/api/{feature}.types.ts
Agent-skill-web/src/types/{feature}.ts

Tao type moi neu chua co:

// Request type (tu Zod schema)
export interface {FeatureName}Request {
  field1: string
  field2?: number  // optional
}

// Response type
export interface {FeatureName}Response {
  success: boolean
  data: {FeatureData}
  message: string
}

// Data type
export interface {FeatureData} {
  id: string
  field1: string
  field2: number
}

Buoc 2.3: Tao/Cap Nhat Service

Tim hoac tao file:

Agent-skill-web/src/api/services/{feature}-service.ts

Tao method:

static async methodName(params: ParamsType): Promise<ResponseType> {
  const response = await apiClient.{method}(
    API_ENDPOINTS.{FEATURE}.{ACTION},
    { params }  // hoac body cho POST
  )
  return response.data
}

PHASE 3: Dong Bo & Kiem Tra

Buoc 3.1: So Sanh Types

So sanh cau truc:

• •Backend response fields vs Frontend type fields
• •Backend Zod schema vs Frontend request type
• •Nested objects va arrays

Buoc 3.2: Cap Nhat Khong Khop

Neu types khong khop:

1. •Them truong moi: Neu backend co truong moi
2. •Sua kieu du lieu: Neu type khac nhau
3. •Xoa truong cu: Neu backend da xoa (can than)

Buoc 3.3: Xac Nhan Dong Bo

Kiem tra:

• • Types frontend khop voi response backend
• • Service method goi dung endpoint
• • Request params/body dung format
• • Error handling phu hop

Vi Du Su Dung

Input: File API

/home/steve/Desktop/Intern/work/Flower/Agent-skill-api/src/app/api/v1/get-store/route.ts

Output:

1. •Tai lieu tai docs/api/get-store/index.md
2. •Types cap nhat trong Agent-skill-web/src/types/
3. •Endpoint them trong Agent-skill-web/src/api/endpoints.ts
4. •Service cap nhat trong Agent-skill-web/src/services/

Luu Y Quan Trong

Naming Conventions

Kiem Tra Truoc Khi Cap Nhat

1. •Khong ghi de code nguoi dung da viet
2. •Giu lai comments va logic cu
3. •Chi them/cap nhat truong can thiet
4. •Backup file truoc khi sua doi lon

Duong Dan Quan Trong

Backend:
- API: Agent-skill-api/src/app/api/v1/
- Lib: Agent-skill-api/src/lib/api-response.ts
- Types: Agent-skill-api/src/payload-types.ts

Frontend:
- Types: Agent-skill-web/src/types/api/
- Services: Agent-skill-web/src/api/services/
- Endpoints: Agent-skill-web/src/api/endpoints.ts

Resources

references/

• •api-analysis-guide.md: Huong dan chi tiet phan tich API backend

assets/

• •api-doc-template.md: Template cho tai lieu API

Trigger Phrases

Skill nay duoc kich hoat khi nguoi dung:

Nghien Cuu API

• •"nghien cuu API nay"
• •"doc API"
• •"hieu API hoat dong"
• •"API nay lam gi"

Phan Tich API

• •"phan tich API"
• •"analyze API"
• •"tao tai lieu API"
• •"document API"

Ghep API

• •"ghep API"
• •"integrate API"
• •"tich hop API"
• •"tao service cho API"
• •"ket noi frontend voi API"

Dong Bo Cau Truc

• •"dong bo types"
• •"sync types"
• •"cap nhat types tu backend"
• •"backend da thay doi, cap nhat frontend"
• •"types khong khop, sua lai"
• •"API da sua, dong bo lai"