Skip to main content

API Review Checklist

Design quality assurance for REST, GraphQL, and gRPC interfaces including security, documentation, and reliability

TL;DR​

APIs are contracts between systems. Breaking APIs is costly—consumers depend on them. This checklist ensures APIs are well-designed, secure, properly documented, and maintainable before publication. Review APIs before finalizing contracts, not after.

Learning Objectives​

After using this checklist, you will be able to:

  • Evaluate API design against industry standards
  • Identify security vulnerabilities in API design
  • Assess versioning and backward compatibility strategies
  • Verify comprehensive documentation
  • Plan for rate limiting and resilience
  • Evaluate error handling and response consistency

API Review Checklist​

Design & Consistency​

  • API Style Consistency
  • Design style consistently applied across all endpoints
  • Naming conventions consistent (camelCase, snake_case, etc.)
  • HTTP methods used correctly (GET, POST, PUT, PATCH, DELETE)
  • Resource naming follows convention (/users, not /getUsers)
  • Request/Response Format
  • JSON schema or equivalent defined
  • Response codes consistent and documented
  • Pagination strategy defined for list endpoints
  • Filtering, sorting capabilities documented
  • API Maturity
  • Response format supports evolution (additional fields safe)
  • Deprecation strategy defined for fields/endpoints
  • No implementation details leaked in responses

Security & Authorization​

  • Authentication
  • Token/credential handling secure (HTTPS only, HttpOnly cookies)
  • Token expiration and refresh strategy defined
  • No credentials in URLs or logs
  • Rate limiting on authentication endpoints
  • Authorization
  • Scopes/permissions documented
  • Principle of least privilege enforced
  • User can only access own data (unless admin)
  • Admin-only endpoints protected
  • Data Protection
  • HSTS header configured
  • Sensitive data not exposed in responses (passwords, tokens)
  • Sensitive data masked in logs and monitoring
  • Data validation prevents injection attacks (SQL, command)
  • API Security Headers
  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY (if applicable)
  • CORS policy explicitly configured (not * allowing all)
  • Rate limiting headers included

Versioning & Backward Compatibility​

  • Versioning Strategy
  • Version number format documented (semantic versioning)
  • API version clearly communicated to consumers
  • Deprecation timeline communicated (minimum 6 months notice)
  • Sunset date included in response headers
  • Backward Compatibility
  • Changing field names or types requires new API version
  • Adding optional fields to responses doesn't break consumers
  • Consumers can ignore unknown fields safely
  • Enum values can be added without breaking clients
  • Multiple Version Support
  • Backward compatibility testing automated
  • Version support lifecycle documented
  • Old versions retired after deprecation period

Documentation​

  • Endpoint Documentation
  • Request parameters fully documented (required, type, format)
  • Response examples provided for all response codes
  • Authentication and authorization requirements clear
  • Rate limits documented
  • API Documentation Quality
  • Authentication flows documented with examples
  • Common error scenarios and handling documented
  • Pagination and filtering usage examples provided
  • Sample code/SDKs provided for popular languages
  • Quickstart & Guides
  • Troubleshooting guide documents common issues
  • Migration guides exist for major version changes
  • Changelog maintained and updated with each release
  • API sandbox/test environment available

Error Handling​

  • Error Response Format
  • Error codes unique and searchable (not just HTTP status)
  • Error messages descriptive and actionable
  • Error messages don't leak security information
  • Structured error responses include error type and code
  • HTTP Status Codes
  • 400 for invalid request, 401 for auth, 403 for authz, 404 for not found
  • 429 for rate limit, 5xx for internal errors
  • Consistent status code usage across API
  • Status code meanings documented
  • Error Recovery
  • Request IDs included in responses for troubleshooting
  • Timeout behavior documented (when to retry vs. fail)
  • Circuit breaker patterns tested for external API calls

Performance & Scalability​

  • Response Performance
  • Response size reasonable (not excessive data)
  • Caching headers implemented (Cache-Control, ETag)
  • Compression enabled (gzip/brotli)
  • Query optimization validated (N+1 problems eliminated)
  • Scalability
  • Request size limits enforced
  • Connection pooling configured
  • Load testing completed for expected peak load
  • Auto-scaling plan documented

Rate Limiting & Throttling​

  • Rate Limit Configuration
  • Different limits for authenticated vs. anonymous users
  • Burst capacity considered (temporary spikes allowed)
  • Rate limit headers communicated (RateLimit-Limit, RateLimit-Remaining)
  • Retry-After header included with 429 responses
  • Fairness & Abuse Prevention
  • DDoS protection configured (WAF, rate limiting at edge)
  • IP-based blocking for abuse patterns
  • Monitoring for unusual usage patterns

Observability & Monitoring​

  • Logging
  • Sensitive data not logged (no passwords, API keys, PII)
  • Log aggregation configured
  • Log retention policy implemented
  • Metrics & Tracing
  • Error rates monitored by endpoint
  • Distributed tracing implemented for microservices
  • Dashboards created for operations team
  • Alerts configured for anomalies

Common API Review Mistakes​

What NOT to Do

Changing API without versioning: Breaking changes without version management alienate consumers and create support burden.

Coupling API to database schema: Exposing database fields directly limits flexibility. Use DTOs and mappers for independence.

Leaking security information in errors: Detailed error messages revealing implementation details aid attackers. Keep errors generic; log details internally.

Ignoring pagination: Returning unbounded results on large datasets causes performance problems. Always paginate list endpoints.

No backward compatibility plan: Adding required fields or changing response structures breaks consumers. Plan for evolution from day one.

Insufficient rate limiting: Vulnerable to abuse and DoS attacks. Always implement appropriate rate limits.

No API versioning strategy: Decisions on versioning made ad-hoc create confusion. Define strategy upfront.

API Review Workflow​

  1. Define API Requirements

    • What problems does this API solve?
    • Who are the consumers (internal, external, public)?
    • What guarantees are required (availability, latency)?
    • What security requirements exist?

  2. Choose Style

    • REST: Simple resource-based APIs, good for CRUD operations
    • GraphQL: Complex query requirements, multiple client types
    • gRPC: High-performance, typed communication between services

  3. Create OpenAPI/Spec

    • Document all endpoints, parameters, responses
    • Generate code from spec (contracts-first approach)
    • Share spec with consumers for feedback

Self-Check​

Before publishing your API, verify:

  • API design is consistent (naming, structure, patterns)
  • Authentication and authorization implemented on all endpoints
  • Documentation is comprehensive and up-to-date
  • Error handling is consistent and informative
  • Rate limiting prevents abuse while allowing legitimate use
  • Backward compatibility strategy documented
  • Performance meets requirements (latency, throughput)
  • All endpoints tested (functional, integration, load)
  • Security review completed
  • Consumers have clear migration path for versions

One Takeaway​

One Takeaway

API design is not about perfection in the first version—it's about choosing evolution strategies that let you improve without breaking consumers. Versioning, deprecation paths, and backward compatibility planning matter more than getting every detail right initially.

Next Steps​

  1. Document API requirements and design philosophy
  2. Create OpenAPI spec and iterate with consumers
  3. Implement rate limiting before publishing
  4. Create comprehensive documentation with examples
  5. Establish versioning strategy and deprecation policy
  6. Set up monitoring for performance and errors

References​