cyh-tk-backend/docs/api-standard.md

API Standard

This document defines the API contract for the TikTok short drama backend. All current and future endpoints must follow this standard.

Base Rules

• API style: RESTful API.
• Response content type: application/json.
• All responses must include requestId.
• requestId must be UUID v4.
• The client may pass X-Request-Id; if it is a valid UUID v4, the server reuses it.
• If X-Request-Id is missing or invalid, the server generates a new UUID v4.
• requestId is the primary lookup key for request logs.
• cost is the server-side request duration, formatted as a string such as 3ms.
• timestamp is the server response time in ISO 8601 format.
• data must always exist. Use {} for empty object responses. Paginated list responses must use data.list.

Success Response

{
  "code": 0,
  "data": {},
  "message": "success",
  "timestamp": "2026-06-30T00:00:00.000Z",
  "requestId": "0f5c2e16-1e44-4d55-93a4-ef7c66d9d1f2",
  "cost": "3ms"
}

List Response

{
  "code": 0,
  "data": {
    "list": [],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 100
    }
  },
  "message": "success",
  "timestamp": "2026-06-30T00:00:00.000Z",
  "requestId": "0f5c2e16-1e44-4d55-93a4-ef7c66d9d1f2",
  "cost": "3ms"
}

Error Response

{
  "code": 403,
  "data": {},
  "message": "No permission",
  "timestamp": "2026-06-30T00:00:00.000Z",
  "requestId": "0f5c2e16-1e44-4d55-93a4-ef7c66d9d1f2",
  "cost": "3ms"
}

Code Rules

• 0: success.
• 400: invalid request parameters.
• 401: not authenticated.
• 403: no permission.
• 404: resource not found.
• 409: conflict, duplicate operation, or invalid state transition.
• 422: business validation failed.
• 429: too many requests.
• 500: internal server error.

HTTP status codes should match the response code for errors. For successful responses, use the correct HTTP status code such as 200 or 201, while response code remains 0.

Request Log Rules

Every API request must create one request log record.

The request log must include:

• requestId
• method
• path
• query
• body
• statusCode
• responseCode
• message
• costMs
• userId
• adminId
• ip
• userAgent
• errorStack
• createdAt

requestId must have a unique index in the request log table.

Admin log endpoints:

• GET /api/admin/v1/logs/requests
• GET /api/admin/v1/logs/requests/:requestId

Playback Error Log Rules

The app must be able to report video playback errors.

Endpoint:

• POST /api/app/v1/logs/playback-errors

Request body:

{
  "requestId": "0f5c2e16-1e44-4d55-93a4-ef7c66d9d1f2",
  "dramaId": 1,
  "episodeId": 10,
  "playUrl": "https://cdn.example.com/video.mp4",
  "playerErrorCode": "MEDIA_DECODE_ERROR",
  "message": "Video decode failed",
  "progressSeconds": 128,
  "networkType": "wifi",
  "device": {
    "platform": "ios",
    "model": "iPhone",
    "systemVersion": "17.0",
    "appVersion": "1.0.0"
  },
  "occurredAt": "2026-06-30T00:00:00.000Z"
}

The playback error log must include:

• id
• requestId
• userId
• dramaId
• episodeId
• playUrl
• playerErrorCode
• message
• progressSeconds
• networkType
• device
• occurredAt
• createdAt

PlaybackErrorLog.requestId must have a normal index so playback errors can be linked with request logs.

Admin playback error endpoints:

• GET /api/admin/v1/logs/playback-errors
• GET /api/admin/v1/logs/playback-errors/:id

Implementation Requirements

The NestJS implementation must include:

• RequestIdMiddleware to generate or validate requestId.
• A global response interceptor to wrap successful responses.
• A global exception filter to wrap error responses.
• A request logging interceptor or middleware to write request logs.
• DTO validation with class-validator.
• Swagger/OpenAPI definitions for all endpoints.
• Tests that verify every endpoint includes code, data, message, timestamp, requestId, and cost.

Admin Permission Rules

Admin APIs under /api/admin/v1/* must require an admin bearer token, except /api/admin/v1/auth/login.

The backend uses RBAC:

• Permission: atomic capability, such as drama:create.
• Role: a group of permissions.
• AdminUser: an admin account with one or more roles.
• Super admin accounts bypass permission checks.

Default local super admin:

username: admin
password: admin123

Core admin endpoints:

• POST /api/admin/v1/auth/login
• GET /api/admin/v1/auth/profile
• GET /api/admin/v1/permissions
• POST /api/admin/v1/permissions
• GET /api/admin/v1/roles
• POST /api/admin/v1/roles
• GET /api/admin/v1/admin-users
• POST /api/admin/v1/admin-users
• PATCH /api/admin/v1/admin-users/:id/status
• GET /api/admin/v1/users
• GET /api/admin/v1/users/:id
• PATCH /api/admin/v1/users/:id/status

Core Domain Modules

The backend is organized around these modules:

• auth: TikTok code exchange placeholder, local user_id binding, app access token issuing.
• drama: album list, episode list, free or paid state, review and publish state.
• media: cover records, video upload jobs, BytePlus vid, TikTok album or episode sync placeholders.
• payment: SKU or unlock price, trade order, TikTok order id, webhook status, unlock records.
• player: album id, episode id, BytePlus vid, play auth token, and playback permission checks.
• admin: drama upload, episode edits, review submit, publish or offline, order and playback data.

Core table targets:

• users: id, tiktok_open_id, nickname, avatar, created_at.
• drama_albums: id, tiktok_album_id, title, description, cover_id, cover_url, status, online_version.
• drama_episodes: id, album_id, tiktok_episode_id, seq, title, byteplus_vid, cover_id, free_type, price, review_status, publish_status.
• orders: id, user_id, album_id, episode_id, tiktok_order_id, trade_order_id, amount, status.
• unlock_records: id, user_id, episode_id, source, created_at.
• media_upload_jobs: id, job_id, byteplus_vid, status, raw_response.