api-contract-review

name	api-contract-review
enabled	true
description	Use when performing api contract review — provides a structured review checklist for evaluating API contracts including REST, gRPC, and GraphQL endpoints. This template covers naming conventions, versioning, error handling, pagination, authentication, rate limiting, and backward compatibility to ensure APIs meet organizational standards before launch.
required_connections	[{"prefix":"api-docs","label":"API Documentation Platform"}]
config_fields	[{"key":"api_name","label":"API Name","required":true,"placeholder":"e.g., Orders API v2"},{"key":"api_type","label":"API Type","required":true,"placeholder":"e.g., REST, gRPC, GraphQL"},{"key":"api_spec_url","label":"API Specification URL","required":false,"placeholder":"e.g., link to OpenAPI spec"}]
features	["API_REVIEW","CONTRACT","ARCHITECTURE"]

API Contract Review

Phase 1: General Design Review

Evaluate overall API design quality.

• API follows organizational naming conventions
• Resources/entities are named using nouns (REST)
• Consistent casing (camelCase, snake_case) throughout
• Versioning strategy defined (URL path, header, query param)
• API specification file exists (OpenAPI, protobuf, GraphQL schema)
• Description and documentation for all endpoints
• Examples provided for request/response bodies

Phase 2: Endpoint Review

For each endpoint:

Endpoint	Method	Auth	Rate Limited	Paginated	Idempotent	Cacheable
		Y/N	Y/N	Y/N	Y/N	Y/N

Request Validation:

• All inputs validated and documented
• Required vs optional fields clearly marked
• Input size limits defined
• Content type specified
• File upload limits defined (if applicable)

Response Design:

• Consistent response envelope structure
• Appropriate HTTP status codes used
• Response fields documented with types
• Nullable fields clearly marked
• No sensitive data leaked in responses

Phase 3: Error Handling Review

• Error response format is consistent across all endpoints
• Error codes are documented and unique
• Error messages are helpful but do not leak internal details
• Validation errors return field-level details
• Rate limit errors include retry-after information

Error Response Checklist:

Status Code	Usage	Error Code Defined	Message Template
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
422	Unprocessable
429	Rate Limited
500	Internal Error

Phase 4: Backward Compatibility Assessment

• No existing fields removed
• No existing field types changed
• No required fields added to existing requests
• No response field semantics changed
• Deprecation notices added for fields being phased out
• Migration guide provided for breaking changes

Breaking Change Checklist:

Change	Breaking?	Migration Path	Timeline
	Y/N

Phase 5: Security and Performance Review

Security:

• Authentication mechanism appropriate for use case
• Authorization checks documented (who can access what)
• Sensitive data not included in URLs or query parameters
• CORS configuration appropriate
• Input sanitization prevents injection attacks

Performance:

• Pagination implemented for list endpoints
• Response size is bounded
• Appropriate caching headers defined
• Bulk/batch endpoints available where needed
• Rate limits defined and documented

Counter-Rationalizations

Shortcut	Counter	Why
"We can skip some steps for this case"	Adapt the workflow steps, don't skip them	Skipped steps are where incidents and oversights originate
"The user seems to already know what to do"	Complete all workflow phases with the user	The workflow catches blind spots that experience alone misses
"This is a minor case, full process is overkill"	Scale the process down, don't turn it off	Minor cases become major when unstructured; the process scales, not disappears
"I'll fill in the details later"	Complete each section before moving on	Deferred details are forgotten; real-time capture is more accurate
"The template output isn't necessary"	Always produce the structured output format	Structured output enables comparison, audit trails, and handoff to other teams

Output Format

Summary

• API: ___
• Type: ___
• Endpoints reviewed: ___
• Issues found: ___ (Critical: ___, High: ___, Medium: ___, Low: ___)
• Backward compatible: Y/N

Action Items

• Fix all Critical and High issues before launch
• Address Medium issues before GA
• Update API specification with all findings
• Publish API documentation
• Set up contract testing
• Communicate breaking changes to consumers