Better understanding of API audit checklist principles

API Audit Checklist

A lifecycle-based checklist to verify API readiness across design, delivery, publishing, and compliance using defined audit criteria and evidence.

How it works

Steps

Use the API Audit Checklist to ensure the API design meets functional and non-functional requirements, including security, performance, and compliance.
Conduct audits to assess lifecycle coverage and verify that the API meets business, design, and operational standards.
Ensure that documentation, security models, gateway configuration, and legal requirements are clearly defined, validated, and supported by evidence.

Example Run

Field	Value
Profile	`read-only`
Generated at	2026-04-06T21:06:36.908Z
OpenAPI path	`specs\openapi\api.yaml`
Checklist path	`specs\audit\api-audit-checklist.json`
Checklist source	local-override
Spectral status	pass
Spectral errors	0
Spectral warnings	0

Summary

Status	Count
Pass	14
Partial	7
Gap	12
N/A	4
Total	37

Stage Summary

Stage	Pass	Partial	Gap	N/A	Total
Strategy	1	1	0	0	2
Architecture	0	2	1	0	3
Design	11	2	3	3	19
Delivery	2	1	4	1	8
Publishing	0	1	4	0	5
Improving	0	0	0	0	0

Audit Items

Stage	Id	Label	Status	Kind	Guidelines	Stations	Criteria	Evidence tags	Expected evidence	Actual evidence	Reason
Strategy	`based-on-clear-business-needs`	API is based on clear business needs	partial	manual	`REST-DOMAIN-01`	`api-product-strategy`	`business-goals-defined`, `market-research-done`, `stakeholder-approval`, `metrics-feedback-available`	`design-artifact`, `documentation`, `research`	`specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json`, `specs/canvases/api-product-strategy/apiBusinessModelCanvas.empty.json`
Strategy	`concept-items-audited`	All concept checklist items are audited	pass	aggregate	`REST-AUDIT-02`	`api-product-strategy`, `api-consumer-experience`	`business-goals-defined`, `market-research-done`, `stakeholder-approval`, `metrics-feedback-available`, `api-opportunity-documented`, `api-reusability`, `value-prop-validated`, `consumer-segments-identified`	`report`	`audit/concept-review-report.json`	`strategy`
Architecture	`versioning-decided`	Versioning strategy decided and supported by gateway	partial	manual	`REST-VERSION-01`	`api-platform-architecture`, `api-publishing`	`api-roadmap-defined`, `api-reusability`, `api-ready-for-publishing`	`spec`, `ci-cd`, `gateway-config`	`specs/openapi/api.yaml`, `docs/api/architecture/README.md`, `docs/api/publishing/README.md`	`specs/openapi/api.yaml`
Architecture	`only-via-gateway`	Only accessible via API gateway	gap	manual	`REST-PUBLISH-02`, `REST-CAPACITY-02`	`api-platform-architecture`, `api-publishing`	`api-reusability`, `api-ready-for-publishing`, `audit-passed`	`gateway-config`, `infra-config`, `security-config`	`docs/api/architecture/README.md`, `docs/api/publishing/README.md`
Architecture	`rate-limits-enforced`	Rate limits are enforced	partial	manual	`REST-CAPACITY-01`, `REST-OBS-01`, `REST-SEC-04`	`api-platform-architecture`	`api-roadmap-defined`, `api-reusability`	`gateway-config`, `runtime`, `monitoring`	`specs/canvases/api-platform-architecture/capacityCanvas.empty.json`, `docs/api/architecture/README.md`
Design	`endpoint-descriptions-present`	Endpoints have business value and feature descriptions	pass	openapi	`REST-CX-01`	`api-design`, `api-consumer-experience`	`design-reflects-business-value`, `value-prop-validated`, `api-opportunity-documented`	`spec`, `design-artifact`	`specs/openapi/api.yaml`, `specs/canvases/api-product-strategy/apiValuePropositionCanvas.empty.json`	`specs/openapi/api.yaml`
Design	`hides-raw-backend-data`	API hides raw backend data and is designed for shared use	partial	manual	`REST-DOMAIN-01`	`api-design`	`hide-backend-discrepancies`, `design-reflects-business-value`	`spec`, `design-artifact`	`specs/canvases/api-product-strategy/domainCanvas.empty.json`, `specs/canvases/api-design/interactionCanvas.empty.json`, `specs/openapi/api.yaml`	`specs/openapi/api.yaml`
Design	`design-consistent`	API design is consistent with other APIs	partial	manual	`REST-DOMAIN-02`, `REST-CX-03`	`api-design`, `api-platform-architecture`	`api-consistency`, `architecture-patterns-validated`, `api-reusability`	`documentation`, `design-artifact`	`specs/canvases/api-design/restCanvas.empty.json`, `docs/api/design/README.md`
Design	`descriptive-english-naming`	Data and attribute naming uses descriptive English	pass	openapi	`REST-NAMING-01`	`api-design`	`api-consistency`	`spec`	`specs/openapi/api.yaml`	`specs/openapi/api.yaml`
Design	`mandatory-fields-specified`	Mandatory fields are specified	pass	openapi	`REST-VALIDATION-01`	`api-design`	`architecture-patterns-validated`, `api-consistency`	`spec`, `contract`	`specs/openapi/api.yaml`	`specs/openapi/api.yaml`
Design	`dates-use-iso`	Dates use ISO format with timezone	gap	openapi	`REST-DATA-01`	`api-design`	`api-consistency`	`spec`	`specs/openapi/api.yaml`	`specs/openapi/api.yaml`
Design	`general-data-uses-standard-values`	General data uses standard values	pass	openapi	`REST-DATA-02`	`api-design`	`api-consistency`, `design-reflects-business-value`	`spec`	`specs/openapi/api.yaml`	`specs/openapi/api.yaml`
Design	`field-names-avoid-acronyms`	Field names avoid acronyms and use full words	pass	openapi	`REST-NAMING-02`	`api-design`	`api-consistency`	`spec`	`specs/openapi/api.yaml`	`specs/openapi/api.yaml`
Design	`paths-max-two-resources`	Endpoint paths contain max two resources or sub-resources	pass	openapi	`REST-PATH-01`	`api-design`	`api-consistency`	`spec`	`specs/openapi/api.yaml`	`specs/openapi/api.yaml`
Design	`examples-present`	Endpoints and attributes include examples	pass	openapi	`REST-CX-02`	`api-design`, `api-consumer-experience`	`design-reflects-business-value`, `value-prop-validated`	`spec`	`specs/openapi/api.yaml`	`specs/openapi/api.yaml`
Design	`get-no-request-body`	GET has no request body and returns content	pass	openapi	`REST-HTTP-GET-01`, `REST-RESP-200-01`	`api-design`	`api-consistency`	`spec`	`specs/openapi/api.yaml`	`specs/openapi/api.yaml`
Design	`get-empty-returns-204`	GET returns 204 if response body is empty	na	n/a	`REST-RESP-204-02`	`api-design`, `api-consumer-experience`	`api-consistency`, `value-prop-validated`	`spec`	`specs/openapi/api.yaml`	`specs/openapi/api.yaml`	The current contract returns content for all GET operations.
Design	`400-errors-specific`	400 errors provide specific error information	gap	openapi	`REST-ERROR-400-01`	`api-design`, `api-consumer-experience`	`design-reflects-business-value`, `api-consistency`, `value-prop-validated`	`spec`	`specs/openapi/api.yaml`	`GET /items/by-slug/{slug}`, `GET /categories/{categoryId}/items`
Design	`401-unauthorized`	401 Unauthorized for wrong credentials	na	n/a	`REST-ERROR-401-01`, `REST-SEC-01`, `REST-SEC-03`	`api-design`, `api-publishing`	`api-consistency`, `api-ready-for-publishing`	`spec`, `security-config`, `gateway-config`	`specs/openapi/api.yaml`	`specs/openapi/api.yaml`	The current public storefront contract is intentionally unauthenticated.
Design	`403-forbidden`	403 Forbidden for unauthorized operations	na	n/a	`REST-ERROR-403-01`, `REST-SEC-03`	`api-design`, `api-publishing`	`api-consistency`, `api-ready-for-publishing`	`spec`, `security-config`, `gateway-config`	`specs/openapi/api.yaml`	`specs/openapi/api.yaml`	The current profile is public read-only and exposes no unauthorized operations.
Design	`spec-contains-schemas`	Spec contains request and response schema	pass	openapi	`REST-CONTRACT-01`	`api-design`	`architecture-patterns-validated`, `api-consistency`	`spec`, `contract`	`specs/openapi/api.yaml`	`specs/openapi/api.yaml`
Design	`pseudo-identifiers`	UUIDs or pseudo-identifiers instead of DB IDs	gap	openapi	`REST-SEC-07`	`api-design`	`hide-backend-discrepancies`, `api-consistency`	`spec`	`specs/openapi/api.yaml`	`productId`, `variantId`, `categoryId`
Design	`no-sensitive-data-in-urls`	No sensitive data in URLs	pass	openapi	`REST-SEC-06`, `REST-SEC-04`	`api-design`	`hide-backend-discrepancies`, `api-consistency`	`spec`	`specs/openapi/api.yaml`	`specs/openapi/api.yaml`
Design	`http-methods-match-resources`	HTTP methods only for intended resources	pass	openapi	`REST-HTTP-GET-01`, `REST-HTTP-POST-01`, `REST-HTTP-PUT-01`, `REST-HTTP-DELETE-01`	`api-design`	`api-consistency`	`spec`	`specs/openapi/api.yaml`	`specs/openapi/api.yaml`
Delivery	`design-items-audited`	All prototype and design items are audited	pass	aggregate	`REST-AUDIT-02`	`api-design`, `api-delivery`	`architecture-patterns-validated`, `design-reflects-business-value`, `api-consistency`	`report`	`audit/production-readiness-review.json`	`design`
Delivery	`spec-validated-on-change`	Spec validated on every change	gap	openapi	`REST-AUDIT-01`	`api-delivery`	`architecture-patterns-validated`, `api-consistency`	`ci-cd`, `spec`, `test`	`.github/workflows/openapi-lint.yml`, `specs/openapi/api.yaml`	`specs/openapi/api.yaml`
Delivery	`schema-and-examples-pass`	Schema and examples pass validation	pass	openapi	`REST-AUDIT-01`, `REST-CONTRACT-01`	`api-delivery`, `api-design`	`api-consistency`, `architecture-patterns-validated`, `api-contract-tested`	`spec`, `test`	`specs/openapi/api.yaml`	`specs/openapi/api.yaml`
Delivery	`uses-https`	Uses HTTPS or encrypted protocols	gap	manual	`REST-SEC-05`	`api-delivery`, `api-publishing`	`architecture-patterns-validated`, `api-ready-for-publishing`	`security-config`, `gateway-config`	`docs/api/delivery/README.md`, `docs/api/publishing/README.md`
Delivery	`inputs-auto-validated`	Inputs auto-validated by framework	partial	manual	`REST-VALIDATION-01`	`api-delivery`	`architecture-patterns-validated`, `api-consistency`	`code`, `test`, `spec`	`specs/openapi/api.yaml`, `docs/api/delivery/README.md`	`specs/openapi/api.yaml`
Delivery	`outputs-auto-escaped`	Outputs auto-escaped by framework	na	n/a	`REST-SEC-04`	`api-delivery`	`architecture-patterns-validated`, `api-consistency`	`code`	`docs/api/delivery/README.md`		JSON APIs do not typically require output escaping in the same way as HTML rendering.
Delivery	`encryption-in-transit`	Encryption for data in transit and storage	gap	manual	`REST-SEC-05`	`api-delivery`, `api-publishing`	`architecture-patterns-validated`, `api-ready-for-publishing`, `audit-passed`	`security-config`, `infra-config`, `documentation`	`docs/api/delivery/README.md`, `docs/api/publishing/README.md`
Delivery	`message-integrity`	Message integrity implemented	gap	manual	`REST-OBS-01`, `REST-SEC-04`	`api-delivery`	`architecture-patterns-validated`, `api-consistency`	`security-config`, `monitoring`, `documentation`	`docs/api/delivery/README.md`, `docs/api/architecture/README.md`
Publishing	`published-via-api-management`	Published via API management	gap	manual	`REST-PUBLISH-01`	`api-publishing`	`api-ready-for-publishing`, `audit-passed`	`gateway-config`, `ci-cd`, `documentation`	`.github/workflows/openapi-lint.yml`, `docs/api/publishing/README.md`
Publishing	`visible-in-dev-portal`	Visible in developer portal	gap	manual	`REST-PUBLISH-03`	`api-publishing`	`api-documentation-ready`, `api-ready-for-publishing`	`documentation`, `runtime`	`docs/api/publishing/README.md`
Publishing	`docs-auto-generated`	Docs auto-generated from spec and schema	partial	manual	`REST-CONTRACT-02`, `REST-PUBLISH-03`	`api-publishing`, `api-delivery`	`api-documentation-ready`, `api-ready-for-publishing`, `api-consistency`	`spec`, `documentation`, `ci-cd`	`specs/openapi/api.yaml`, `docs/api/publishing/README.md`, `docs/api/audit/design-audit.read-only.md`	`specs/openapi/api.yaml`
Publishing	`spec-auto-updated`	Spec auto-updated to gateway and dev portal	gap	manual	`REST-CONTRACT-02`	`api-publishing`, `api-delivery`	`api-ready-for-publishing`, `audit-passed`, `api-consistency`	`ci-cd`, `gateway-config`, `documentation`	`.github/workflows/openapi-lint.yml`, `docs/api/publishing/README.md`, `specs/openapi/api.yaml`	`specs/openapi/api.yaml`
Publishing	`official-domain`	Published under official organization domain	gap	manual	`REST-PUBLISH-04`	`api-publishing`	`api-ready-for-publishing`, `audit-passed`	`documentation`, `runtime`	`docs/api/publishing/README.md`