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: Backend / API-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.

API architecture and contracts#

• APID-001 Define each API's business purpose, owner, intended consumers, and trust boundary.

• APID-002 Choose synchronous HTTP, asynchronous events, or streaming based on consistency and latency needs.

• APID-007 Apply correct HTTP safety and idempotency semantics for HTTP methods when applicable.

• APID-012 Document validation, authentication, authorization, conflict, overload, and server-failure responses.

• APID-017 Specify appropriate cache directives, validators, freshness, and private-data isolation.

• APID-003 Separate public, partner, internal, and privileged operations with documented authorization policies.

• APID-004 Keep a reviewed OpenAPI, AsyncAPI, or equivalent contract appropriate to the protocol.

• APID-005 Validate implemented methods, routes, events, and message types against the published contract.

• APID-006 Use predictable resource names, identifiers, and documented operation semantics.

• APID-008 Specify accepted content types, content negotiation, and unsupported representation behavior.

• APID-009 Define field types, required properties, nullability, defaults, and unknown-field behavior.

• APID-010 Specify timestamp/time-zone, numeric precision, currency, Unicode, and locale semantics.

• APID-011 Use explicit schemas for nested, polymorphic, and potentially large payloads.

• APID-013 Adopt consistent structured errors such as RFC 9457 Problem Details where suitable.

• APID-014 Define stable pagination, sorting, filters, and cursor behavior under data changes.

• APID-015 Document write concurrency control, conditional updates, and lost-update prevention.

• APID-016 Define retry, timeout, deduplication, and idempotency semantics for operations with side effects.

• APID-018 Document file transfers, streams, and asynchronous job completion where provided.

• APID-019 Define authentication schemes, scopes, tenant boundaries, and privileged roles.

• APID-020 Review interface descriptions and executable examples together with the versioned release artifact.

Consumer experience and lifecycle#

• APID-021 Document supported environments, API base URLs, versions, and contact channels.

• APID-037 Distinguish internal service objectives from contractual API support guarantees.

• APID-022 Provide a first-success quickstart using safe test credentials and current examples.

• APID-023 Explain credential issuance, expiry, rotation, and least-privilege scope selection.

• APID-024 Publish representative success, validation, denial, conflict, and throttling examples.

• APID-025 Describe tenant, account, user, and resource identifier scopes clearly.

• APID-026 Document quotas, rate limits, payload limits, and client concurrency expectations.

• APID-027 Explain safe retries and handling of ambiguous timeouts without duplicate actions.

• APID-028 Provide correlation identifiers and support details to diagnose reported errors.

• APID-029 Document pagination traversal, cursor expiry, and stable ordering requirements.

• APID-030 Maintain version-compatible SDKs and code samples where offered.

• APID-031 Verify published code examples against a controlled environment before release.

• APID-032 Explain optional response fields, extensions, feature negotiation, and tolerant parsing.

• APID-033 Offer authoritative contract artifacts for consumer code generation and testing.

• APID-034 Document deprecations, support windows, sunset dates, and migration steps.

• APID-035 Specify asynchronous operation tracking, partial success, and delayed consistency.

• APID-036 Provide representative test fixtures and sandboxes when integration risk warrants them.

• APID-038 Track new-consumer onboarding failures, common integration complaints, and owners.

• APID-039 Test a consumer's ability to find docs, authenticate, complete a task, and recover from failure.

Third-party integrations#

• APID-042 Review provider scopes, API keys, data location, processing terms, and access rights.

• APID-046 Authenticate webhook senders with the provider's supported signature or equivalent mechanism.

• APID-047 Document webhook acknowledgment, retry, duplicate, ordering, and expiry behavior.

• APID-052 Collect safe request, transaction, and provider correlation IDs for incidents.

• APID-040 Inventory providers, data flows, ownership, criticality, terms, and escalation contacts.

• APID-041 Document the intended fallback when a critical third-party integration is unavailable.

• APID-043 Keep development and production credentials and callback destinations separate.

• APID-044 Protect external credentials through approved secret storage and rotation procedures.

• APID-045 Validate and constrain untrusted provider responses before use in business operations.

• APID-048 Deduplicate repeated event deliveries using stable event IDs or business invariants.

• APID-049 Set bounded timeouts, retries, backoff, concurrency limits, and circuit breaking.

• APID-050 Exercise provider outages, slow responses, malformed payloads, and quota exhaustion safely.

• APID-051 Reconcile ambiguous external outcomes against the local source of truth.

• APID-053 Ensure third-party logs and error outputs do not expose unrelated personal data.

• APID-054 Monitor vendor costs, rate limits, quotas, and usage anomalies.

• APID-055 Track provider version changes, SDK support, deprecation notices, and schema drift.

• APID-056 Validate untrusted URLs and callback redirects to mitigate SSRF and open redirects.

• APID-057 Document incident handling, vendor status channels, emergency contacts, and exit options.

• APID-058 Test critical integration scenarios in an authorized sandbox or equivalent controlled environment.

• APID-059 Review any applicable privacy, licensing, cross-border data, or contract requirements.

Versioning and compatibility#

• APID-060 Define a versioning and negotiation policy for each supported API and message interface.

• APID-065 Support old and new API instances or clients coexisting during phased deployment.

• APID-068 Coordinate database/schema evolution with legacy consumers and outstanding background jobs.

• APID-069 Document caching and persisted-client behavior across API versions.

• APID-075 Version and archive API schemas, SDKs, docs, and release artifacts consistently.

• APID-061 Document which contract changes are considered breaking for each consumer category.

• APID-062 Treat field removal, changed types, required inputs, and authorization changes as possible breaks.

• APID-063 Review new enum values and response fields against consumers using closed-schema parsing.

• APID-064 Specify compatibility rules for nullability, defaults, list order, errors, and pagination.

• APID-066 Run a contract-diff check against supported production versions before release.

• APID-067 Use consumer-driven or representative contract tests for important dependent clients.

• APID-070 Announce deprecations with migration guidance and an approved notice period.

• APID-071 Provide safe test environments and examples of required migration steps.

• APID-072 Observe legacy version use where permitted before disabling old interfaces.

• APID-073 Define an exception process for consumers unable to migrate before sunset.

• APID-074 Test compatibility with independently updated vendor SDKs and external providers.

• APID-076 Verify rollback does not leave previous clients incompatible with changed data.

• APID-077 Define responses for unsupported and sunsetted versions and explain next steps.

• APID-078 Assign owners to breaking-change investigations and outstanding compatibility debt.

API Checks#

• APID-079 Test object-, function-, and property-level authorization, including tenant isolation.
• APID-080 Validate inputs, uploads, query options, and request sizes at the trusted API boundary.
• APID-081 Verify actual success and failure status codes and structured errors match contracts.
• APID-082 Test repeated mutations and concurrent requests for idempotency and data integrity.
• APID-083 Validate conditional requests or optimistic locking on sensitive concurrent edits.
• APID-084 Test pagination with inserts, deletions, duplicate sort keys, and empty pages.
• APID-085 Verify rate limits, quotas, overuse errors, and bounded resource consumption.
• APID-086 Test cache headers, privacy boundaries, localization keys, and conditional responses.
• APID-087 Verify cross-origin rules allow intended browser clients but not arbitrary origins.
• APID-088 Test TLS and token audience, issuer, expiry, scope, and authorization checks.
• APID-089 Reject webhook requests with invalid signatures or failed replay safeguards.
• APID-090 Test duplicate, delayed, or out-of-order events without duplicate business side effects.
• APID-091 Simulate upstream and downstream timeouts, malformed data, and partial outages.
• APID-092 Check upload, download, asynchronous job, and streaming completion when applicable.
• APID-093 Validate logs, traces, and error reports exclude credentials and sensitive payloads.
• APID-094 Confirm contract tests and breaking-change checks are required by CI.
• APID-095 Test compatibility across supported client versions and server rollbacks.
• APID-096 Validate Unicode, date, monetary values, and locale metadata end-to-end.
• APID-097 Verify third-party usage controls for cost, payloads, concurrency, and quotas.
• APID-098 Confirm the production deployment identifies responsible API owners and escalation paths.
• APID-099 Check public schema examples and SDK operations against production-equivalent behavior.

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.

• OpenAPI Specification v3.2.1 — machine-readable contracts for HTTP API operations and schemas.
• AsyncAPI Specification v3.1.0 — machine-readable contracts for message-driven interfaces.
• IETF RFC 9110 — HTTP Semantics — methods, statuses, content negotiation, and representation semantics.
• IETF RFC 9111 — HTTP Caching — freshness, validators, cache-control, and private response protection.
• IETF RFC 9457 — Problem Details — structured error responses for HTTP APIs.
• IETF RFC 9700 — OAuth 2.0 Security BCP — current OAuth security guidance for applicable deployments.
• IETF RFC 6750 — Bearer Token Usage — bearer credential transport and error behavior.
• OWASP API Security Top 10 (2023) — authorization, resource consumption, and integration threats.
• JSON Schema Draft 2020-12 — schema contracts and JSON validation.
• CNCF CloudEvents — common metadata for event integrations where appropriate.
• IETF RFC 8288 — Web Linking — link relations for API discoverability where applicable.
• IETF RFC 9421 — HTTP Message Signatures — optional signed HTTP requests and webhook messages.

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 API and service 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 backend / API 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.