| name | api-integration-contract-review |
| description | Reviews frontend-to-backend API contracts — BFF route handlers and direct backend calls — for data-minimization, server-side object-level authorization enforcement, error-shape leakage, CORS misconfiguration, and backward-compatible versioning before they ship. |
| allowed-tools | Read Grep Glob |
| metadata | {"author":"github: Raishin","version":"0.1.0","updated":"2026-07-02","category":"architecture"} |
API Integration Contract Review
Purpose
Review any new or changed API contract consumed by the frontend — a direct backend call or a BFF (backend-for-frontend) route handler — for data-minimization (no field returned to a client that the caller is not authorized to see), object-level authorization enforced independently on the server, error-shape safety (no upstream internals leaking to the client), CORS correctness, and backward-compatible versioning for existing consumers. This skill exists so those four concerns get a disciplined, security-severity review every time a contract is introduced or changed, instead of being waved through as "just wiring."
When to use
Use this skill when the user asks to:
- review a new API endpoint or BFF route handler before it ships,
- review a change to an existing response shape, status-code contract, or error format,
- audit whether the frontend fetches more fields than it renders,
- investigate a reported data-exposure or authorization-bypass (BOLA) concern,
- review CORS configuration for an endpoint that accepts credentialed requests.
Do not use this skill for:
- the frontend's caching/store logic once data has already arrived — route to
state-management-decision-review,
- BFF-vs-direct-call topology or new-BFF-service ownership decisions at the platform level — route to
frontend-platform-architecture-review; use this skill for the contract itself once the boundary decision is made,
- SSR/hydration mechanics — route to the relevant SSR skill,
- general Next.js data-fetching patterns unrelated to authorization/data-shape — route to
nextjs-app-router-data-fetching-review.
Context7 Documentation Protocol
- Before assessing a Next.js Route Handler's caching configuration, query Next.js docs for the current caching-directive semantics (
dynamic, revalidate, fetchCache, runtime) against the repo's confirmed major version — read package.json first. As of Next.js 15+, GET Route Handlers are no longer cached by default; caching requires an explicit export const dynamic = 'force-static'. A route relying on pre-15 default-caching behavior to protect against overexposure (or that assumes it is uncached when it is actually configured force-static) is a version-sensitive misconfiguration risk, not a stylistic detail — verify the version before trusting either claim.
- Matched library ID for this skill's default grounding: Next.js is
/vercel/next.js. Resolve fresh via resolve-library-id for any other backend/BFF framework named in the review (Express, Fastify, NestJS, etc.) rather than assuming Next.js conventions transfer.
- Before approving a query-key or cache-key design that scopes data by session/role, query TanStack Query docs for query-key structuring guidance — object-based key segments are order-independent and
undefined properties are dropped during serialization, so a key intended to separate two roles/users can silently collide if one property is undefined for one caller and omitted for another. Matched library ID: /tanstack/query.
- Documentation proves what the framework supports (e.g., that
force-static exists and changes default caching). It does not prove this specific route handler is configured correctly, or that authorization is actually enforced server-side. Pair every Context7-grounded capability claim with a repo-evidence check (the actual route handler code, the actual authorization middleware) before treating a finding as resolved.
- Never approve a version-sensitive caching or contract claim without Context7 verification. If Context7 is unavailable, label the claim
documentation-based — unverified this session and require confirmation before final sign-off.
Lean operating rules
- Treat every unjustified field in a response as a data-minimization defect, not a style note. "We return the whole object because it's simpler" is not a justification.
- Treat client-supplied identifiers (a URL param, a body field, a bearer-token claim the client can influence) as untrusted for authorization decisions. Object-level authorization must be re-derived server-side from the authenticated session, independent of what the client claims to be requesting.
- Escalate every finding of client-side-only authorization enforcement or excessive data exposure to security severity, not a style/lint-level note — these map directly to OWASP API Security Top 10 categories (Broken Object Level Authorization, Excessive Data Exposure).
- Treat raw upstream error forwarding (stack traces, internal hostnames, DB driver errors, vendor error payloads) as a blocking finding. Error responses reaching the client must be shaped and sanitized, not passed through for "easier debugging."
- Treat wildcard CORS (
Access-Control-Allow-Origin: *) combined with Access-Control-Allow-Credentials: true as an automatic blocking finding — this combination is invalid per the CORS spec in browsers that enforce it correctly, and where it is not rejected outright it defeats the purpose of credentialed requests.
- For a breaking contract change (removed field, renamed field, changed status-code meaning, changed error shape), require an identified list of existing consumers and a stated deprecation window before approval. Do not accept "nothing should be calling this yet" without evidence.
- Never execute, build, or run application code as part of this review; this is a static-review skill (Read/Grep/Glob only) — verdicts are based on route-handler code, authorization middleware, and documented contract evidence, not live requests you generate yourself.
- Label every claim
repo evidence, Context7-verified, documentation-based — unverified this session, or inference. Documentation proves framework capability; it does not prove this endpoint's authorization is correctly wired.
References
Load these only when needed:
Response minimum
Return, at minimum:
- the endpoint/route handler and consumer(s) in scope,
- a per-field data-minimization justification (or the unjustified fields flagged),
- the object-level authorization enforcement mechanism and whether it is independently server-verified,
- error-shape and CORS findings, each labeled by severity,
- verdict (approve / approve-with-conditions / block) with the specific unresolved conditions if any,
- versioning/deprecation plan status for any breaking change,
- every version-sensitive framework claim labeled
Context7-verified or documentation-based — unverified this session.
