Skip to main content

Apifox API Source of Truth

Use Apifox project 8407323 as the source of truth for frontend API schemas, types, endpoints, and service integration

Source: .agents/rules/apifox-api-source-of-truth.mdc

Metadata​

  • name: apifox-api-source-of-truth
  • alwaysApply: true

Content​

Apifox API Source of Truth

For frontend API implementation, use Apifox project 8407323 as the canonical source of truth:

https://app.apifox.com/project/8407323

Required Practice​

  • Before adding or changing API integration, check the relevant Apifox endpoint and schema.
  • This applies to src/services, service-facing request and response types, endpoint paths, query params, payload shapes, response handling, and integration behavior.
  • Treat Apifox as authoritative over inferred backend behavior, copied examples, stale local types, or assumptions from existing frontend code.
  • If existing frontend code conflicts with Apifox, update the frontend contract to match Apifox unless the task explicitly says Apifox is stale.
  • Keep API contracts and service modules under src/services/.
  • Continue using the repo service response pattern: { data, error }.
  • Use TypeScript for new service, type, utility, and API contract files.
  • Do not use any, unsafe as, or invented fallback types to force mismatched API contracts.

Authentication Gate​

  • Before implementing real API/schema work, confirm the agent can access the Apifox project while authenticated.
  • Prefer Apifox CLI authentication first. Follow the official Apifox CLI docs: https://docs.apifox.com/apifox-cli
  • Use a local Apifox API access token with apifox login --with-token <token>, then verify the session with apifox whoami before reading private project schemas.
  • If CLI authentication is unavailable or fails, fall back to an authenticated browser session, such as the in-app browser or the developer's browser profile.
  • Authentication must stay local to the developer or agent environment, such as local Apifox CLI config or an authenticated browser session.
  • Do not commit Apifox tokens, cookies, private headers, exported secrets, credentials, or generated auth files.
  • If Apifox cannot be accessed, mark the API integration as blocked unless the user provides an authenticated export or explicitly confirms UI-only work.
  • If Apifox does not contain the needed endpoint or schema, do not invent the contract. Ask for backend/API clarification or mark the API dependency as blocked.

Review Gate​

  • Use Apifox CLI authentication first when possible, and fall back to an authenticated browser session only when CLI authentication is unavailable or fails.
  • Code review must treat this rule as required whenever the diff touches src/services/, src/hooks/useApi.ts, src/pages/api/, service-facing types, endpoint paths, payloads, query params, or service-style callers.
  • In the review output, state whether the relevant Apifox endpoint/schema was checked in an authenticated session.
  • If the reviewer cannot access Apifox or cannot find the needed endpoint/schema, flag the API integration as blocked or request backend/API clarification. Do not approve invented service contracts.

Implementation Workflow​

  1. Locate the endpoint and schema in Apifox.
  2. Derive request and response TypeScript types from that schema.
  3. Implement or update the service module under src/services/.
  4. Update callers using existing loading, toast, and &#123; data, error &#125; handling patterns.
  5. In the implementation or review summary, state that the relevant Apifox schema was checked.