API Design Review Checklist

When to Use This Checklist

Use this checklist when reviewing a new HTTP API or a significant change to an existing one. Good API design is consistent, predictable, and well-documented, which lowers integration cost and reduces support load. This review applies recognized industry guidelines so reviewers do not rely on personal preference alone.

How to Use This Checklist

Start from the OpenAPI specification, which should be the contract and source of truth before handlers are written. Walk through naming, methods, status codes, and error formats for consistency, then confirm pagination, authentication, and versioning are handled deliberately. Treat the spec as testable: schemas should be validated, and documentation and examples should be generated from it. Use the checklist as a shared standard so reviews are objective and repeatable.

What Good Looks Like

A well-designed API has an OpenAPI spec as its single source of truth, consistent resource naming, and correct use of methods and status codes. Errors follow a standard problem format, and pagination, filtering, and sorting are uniform. Authentication scopes, rate limits, and a clear versioning strategy are documented. Schemas are validated, and human-readable docs and examples are generated from the spec.

Common Pitfalls

The most common pitfall is writing code first and reverse-engineering a spec later, which produces inconsistent endpoints. Custom error shapes per endpoint frustrate clients. Inconsistent pagination and date formats create subtle bugs. Versioning is often an afterthought, forcing breaking changes onto consumers. Finally, documentation that drifts from the implementation erodes trust.

Related Resources

Consult the Google API design guide, Microsoft REST API guidelines, OpenAPI best practices, API-first design, and the Problem Details RFC.