api-integration-contract-review

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:

• Contract review workflow and verdict contract — use for the step-by-step review procedure, the block / block-with-conditions / approve decision tree, and the required output shape.
• Authorization and data-minimization patterns — use when the contract involves per-object access control, role-scoped fields, or a BOLA/excessive-data-exposure concern; grounds server-side enforcement patterns and field-justification review.
• Error shape, CORS, and versioning — use when reviewing error-handling code, CORS configuration, or a breaking/backward-compatible contract change with existing consumers.

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.