Prerequisites & Discovery Inputs
Have the following assets, repositories, and architectural context accessible before executing this evaluation:
- Draft endpoint specs or OpenAPI draft docs
- Authentication and authorization designs
Problem Statement
Poorly designed APIs lead to runtime integration errors, security leaks, and data consistency issues. Use this checklist to design stable and consistent API contracts.
When to Use
Use this checklist during the design phase of new endpoints, or when auditing public and internal APIs for security and developer integration compliance.
Step-by-Step Guide
Step 1: Design URL Paths and Methods
- Use nouns for resource paths and standard HTTP methods.
- Enforce lowercase and hyphenated path structures.
Step 2: Establish Consistent Contracts
- Require structured JSON payloads.
- Use explicit error schemas with proper HTTP status codes.
Step 3: Configure Security Constraints
- Require token authentication for all write endpoints.
- Enforce strict input validation rules before executing database calls.
Checklist Items
- URL paths use plural nouns for resources (e.g.
/users). - Endpoints use correct HTTP status codes (200 for OK, 201 for Created, 400 for Bad Request).
- Write operations support idempotency keys to prevent duplicate actions.
- Rate limits are active and configured per API consumer key.
- All inputs are strictly sanitized and checked against schema filters.
Architectural Invariant · Production Hardening
Architecture specifications are only as sound as their verification in running production. In high-throughput systems, ensure every interface boundary maintains isolated timeout budgets, automated fallback circuits, and zero reliance on unmetered external dependencies.
Frequently Asked Questions
Practical insights on apis executionWhy is idempotency critical for write APIs?
Idempotency prevents duplicate operations (like billing charges or email dispatches) in the event of client retries or network failures.