API with file uploads: If endpoints accept file uploads (images, documents, CSV imports), the API specification in Step 1 must define maximum file size, accepted MIME types, and whether upload is direct (multipart form data to the API) or indirect (pre-signed URL to object storage). File upload endpoints need different timeout and body size limits than standard JSON endpoints.
API consumed by multiple client types with different needs: If the same API serves a web frontend (needs nested objects for fewer requests) and a mobile app (needs flat objects for bandwidth efficiency), design a single representation and use sparse fieldsets (fields query parameter) or separate mobile-specific endpoints. Do not create two complete API surfaces for different clients.
Backward-incompatible schema change after launch: If Step 3 migration needs to rename or remove a column that existing API consumers depend on, use a multi-phase migration: (1) add new column, (2) backfill data, (3) update API to use new column, (4) remove old column in a subsequent release. Never remove a column in the same release that changes the API response format.
API with long-running operations: If any operation takes more than 10 seconds (report generation, bulk import, data export), do not make the client wait. Return 202 Accepted with a status URL, process the operation asynchronously, and let the client poll the status URL for completion. Define the status response format in Step 1.
Zero-downtime API versioning: When introducing a breaking change (removed field, changed response structure), maintain the old version alongside the new version for a defined deprecation period. Document the overlap duration, migration guide for consumers, and sunset timeline in Step 5.
API with rate limiting and abuse prevention: If the API is public-facing or serves third-party integrators, add rate limiting configuration in Step 2 implementation. Define limits per authentication level (unauthenticated: 10 requests per minute, authenticated: 100 per minute, premium: 1,000 per minute). Return 429 Too Many Requests with a Retry-After header. Document rate limits in Step 5 so consumers can build backoff logic. Consider adding request quotas (daily or monthly limits) for API key-based access.
API with webhook delivery: If the API needs to notify external systems of events (order created, payment processed, user signed up), design the webhook system in Step 1 (event types, payload format, retry policy), implement a delivery queue in Step 2 (background worker with exponential backoff, maximum 5 retries over 24 hours), and document the webhook payload format and verification signature in Step 5. Webhook endpoints should be idempotent -- consumers may receive the same event multiple times due to retries.
Migrating from a legacy API: If replacing an existing API with a new implementation, run both versions in parallel during a migration window. Step 1 should document which legacy endpoints are replaced, which are unchanged, and which are new. Step 5's versioning strategy must include a migration guide that maps old endpoints to new endpoints with request/response translation examples.
API with soft-delete requirements: If business rules require that deleted resources remain queryable (audit trails, regulatory compliance, undo functionality), design the soft-delete pattern in Step 1 (deleted_at timestamp column, query filters that exclude soft-deleted records by default), implement it in Step 2 (DELETE endpoint sets deleted_at instead of removing the row, GET endpoints filter by deleted_at IS NULL unless include_deleted=true query parameter is provided), add the deleted_at index in Step 3, and test both deletion and recovery in Step 4.
API serving both internal and external consumers: If the same API serves internal microservices and external third-party developers, separate the authentication in Step 1 (internal: service-to-service mTLS or shared secret, external: API key or OAuth). Rate limits, logging verbosity, and error detail levels should differ between internal and external consumers. Internal consumers receive detailed error messages for debugging; external consumers receive sanitized errors that do not leak implementation details.
High-write API with eventual consistency needs: If the API handles high write volumes (event ingestion, logging, IoT telemetry), the synchronous request-response pattern may not scale. Design an async write path in Step 1 (accept the write, return 202 Accepted, process asynchronously), implement the queue-based pattern in Step 2, and ensure Step 4 tests verify that the async processing completes within the documented SLA.
API with multi-tenancy requirements: If the API serves multiple organizations whose data must be isolated, decide the tenancy model in Step 1: shared database with tenant_id on every table (simplest, best for most cases), schema-per-tenant (moderate isolation, PostgreSQL supports this well), or database-per-tenant (maximum isolation, highest operational cost). In Step 2, add tenant-scoping middleware that injects tenant_id into every database query. In Step 3, create migrations that add tenant_id columns with NOT NULL constraints and composite indexes. In Step 4, write cross-tenant isolation tests that verify one tenant's request never returns another tenant's data.
API requiring idempotency for mutation endpoints: If consumers may retry requests (network timeouts, load balancer retries), mutation endpoints (POST, PUT, PATCH) should support idempotency keys. Design the idempotency pattern in Step 1 (Idempotency-Key header, stored results for duplicate detection), implement a response cache keyed by the idempotency key in Step 2, and test duplicate request handling in Step 4 (same key returns same response without re-executing the operation).
API with search and full-text query requirements: If the API needs search functionality beyond simple column filters (product search, document search, fuzzy matching), evaluate whether the primary database supports adequate full-text search (PostgreSQL's tsvector, MySQL's FULLTEXT) or whether a dedicated search engine (Elasticsearch, Meilisearch, Typesense) is needed. Design the search endpoint in Step 1 with query syntax, faceting, and result highlighting. If using a separate search engine, Step 3 must include the indexing pipeline that keeps the search index synchronized with the primary database. Step 4 tests should verify search relevance with representative queries, not just that the endpoint returns results.