awesomechecklists
llms.txtGitHub ↗
/

07 — API Design and Integrations Checklist#

Verify that service interfaces have understandable contracts, predictable behavior, secure integration boundaries, maintained consumer compatibility, and workable fallback procedures. This checklist complements the separate Security, Testing, Data, DevOps, and Reliability reviews.

Scope: Frontend-specific. This file is one part of the 07_API_Design_and_Integrations.md checklist. Apply the domain-wide release gate across all applicable scope files; each checklist ID remains unique.

Review details#

  • Project / product:
  • Release / version / environment:
  • Scope and applicable jurisdictions / markets:
  • Interface types / external dependencies:
  • API owners / consumers / contract version:
  • Reviewer / owner:
  • Review date:
  • Decision: Pending / Approved / Approved with documented exceptions / Blocked

How to use#

  1. Copy this reusable checklist into project-specific review records; leave all checkboxes in the repository unchecked.
  2. Verify each item with specifications, contract tests, authenticated integration scenarios, documentation, and deployment evidence. Record failed checks, accepted exceptions, and justified N/A in project notes/issues keyed by APID ID, not in this shared template.
  3. Apply only the relevant protocol requirements: HTTP APIs, events, webhooks, streams, and SDKs differ; OpenAPI, OAuth, AsyncAPI, and CloudEvents are not mandatory for every product.
  4. Keep ## API Checks and ## Frontend Checks separate and record inapplicable surfaces in project notes.
  5. Reassess contracts after security, data-model, provider, SDK, messaging, or supported-version changes.

Frontend Checks#

  • APID-100 Map critical browser journeys to the API calls, permissions, and expected errors they depend on.
  • APID-101 Verify client configuration uses intended API origins, versions, and production environment.
  • APID-102 Prevent secrets and privileged API credentials from appearing in public frontend assets.
  • APID-103 Use safe browser credential handling and documented CORS rather than permissive workarounds.
  • APID-104 Render API-supplied user content safely without injecting executable script or markup.
  • APID-105 Validate submitted field types and constraints, while retaining server-side authority.
  • APID-106 Handle validation, conflict, denied, expired-session, offline, and server errors distinctly.
  • APID-107 Bound client retries and guard against duplicate charges, messages, or submissions.
  • APID-108 Offer clear progress, cancellation, and resumption for long-running operations as relevant.
  • APID-109 Handle empty, partial, paginated, and stale data without misleading users.
  • APID-110 Invalidate user-specific caches after writes, role changes, account switches, and logout.
  • APID-111 Prevent private responses being reused across users, tenants, or browser cache contexts.
  • APID-112 Tolerate allowed additional response fields and enum extensions without crashes.
  • APID-113 Test old browser tabs and cached bundles during progressive API deployment.
  • APID-114 Validate upload/download sizes, content types, and understandable failure states.
  • APID-115 Test essential journeys under throttling, provider outages, and intermittent connectivity.
  • APID-116 Make API-related error feedback understandable and accessible to keyboard and screen-reader users.
  • APID-117 Correlate client and API diagnostics without exposing user secrets or protected payloads.
  • APID-118 Keep generated API client types and frontend mocks aligned with approved contracts.
  • APID-119 Document client support and deprecation windows and ensure migration UX is usable.

Release gate#

  • Release-affected interfaces have accountable owners, current accessible contracts, and identified consumers and trust boundaries.
  • Required authentication, authorization, schema conformance, error behavior, and core contract checks pass against the release candidate.
  • Existing supported consumers remain compatible, or a reviewed migration plan and version coexistence strategy are in place.
  • High-impact operations have safe retries, idempotency, concurrency, resource ceilings, and partial-failure handling where applicable.
  • Critical third-party connections use approved credentials, validate untrusted data, and have tested recovery and escalation arrangements.
  • Affected frontend workflows handle API errors, stale responses, caching, authentication, and phased rollouts safely.
  • Published docs, support contacts, changelogs, and deprecation notices reflect the exact release.
  • Material unresolved security, data-integrity, or compatibility risks have explicit authorized release decisions.

Domain-specific approval rule: Block sign-off for unauthorized cross-tenant access, unreviewed breaking changes for supported consumers, unsafe duplicate business side effects, or untested critical provider failure paths without accepted mitigation. This template does not certify security or protocol conformance.

Trusted references and scope#

These primary standards and authoritative guidance inform the checks; use them only for relevant protocols and implementations.

Applicability: OpenAPI 3.2.1 is for HTTP interface descriptions; AsyncAPI 3.1.0 is for message-driven interfaces; verify actual toolchain support. OAuth and bearer guidance applies only where those credential schemes are used. CloudEvents and HTTP message signatures are optional interoperability choices rather than universal webhook obligations. OWASP API Security Top 10 (2023) is risk guidance, not exhaustive certification.

Source review date: 2026-11-12.

Suggested testing tools#

Choose tools appropriate to the project's stack and risks; automation supports evidence but does not approve the checklist.

  • Test focus: API schemas, auth, errors, compatibility, and dependency failures; include browser and client behavior where applicable.
  • Cross-stack: Redocly CLI + Pact.
  • Python: Schemathesis + pytest; for pytest-based suites, run python -m pytest -q.
  • TypeScript: Supertest + Vitest; for Vitest-based suites, run npx vitest run (or npx playwright test for E2E).
  • JavaScript: Dredd + Jest; for Jest-based suites, run npx jest --ci (or npx playwright test for E2E).
  • Evidence: Save tool versions, configuration, test environment, fixtures, results, and links in project-specific review records using the existing checklist IDs. Expert review remains necessary where relevant.

Suggested AI skills for verification#

These are optional agent review aids, not automated passes or release approval. Each linked repository had at least 1,000 GitHub stars when checked on 2026-11-12; counts are per repository, not per skill, and do not indicate security or correctness.

  • api-and-interface-design — Review API contracts, failure states, and evolution (addyosmani/agent-skills, 116,378 repo stars).
  • api-design-principles — Check endpoint, error, and schema consistency (wshobson/agents, 42,437 repo stars).
  • spec-to-code-compliance — Compare implemented API behavior against its contract (trailofbits/skills, 8,150 repo stars).

How to check: In a project-specific copy, have the agent audit the frontend scope and map findings to this file's existing checklist IDs, with code/configuration references, reproducible test results, failed or inapplicable cases, and uncertainties. Independently verify findings; keep shared template boxes unchecked and retain human approval requirements.

Before use: Read the skill's SKILL.md, referenced scripts, license, and requested tool permissions. Only execute vetted skills with appropriate access in a controlled environment.

Important warning: reference only#

⚠️ Reference only — not a definitive or exhaustive checklist. This template is a starting point for review, not the ultimate authority or a guarantee of project safety, quality, regulatory compliance, accessibility, security, or launch readiness.

Use project-specific judgment and independent verification. Requirements and risks evolve and differ by project, technology, and jurisdiction. Adapt the checks, consult current authoritative sources, perform relevant tests, and obtain qualified specialist review or approval when appropriate. Checking every box does not replace these steps.

Reference, not a certification. Check applicability, verify important claims against current primary sources, and seek expert review where necessary. Suggest an improvement.