The API Design Checklist: 10 Things Seniors Do Before Writing a Single Line of Code

6. Enforce Strong Pagination Standards

When a database table contains only fifty records, returning all of them in a JSON list is acceptable.

When that table grows to five million records, a “Select All” query will exhaust the server’s memory, lock the database, and crash the application.

Pagination must be designed into every list endpoint by default.

While Offset Pagination (e.g., “skip 50, take 10”) is common, it suffers from performance issues on large datasets because the database must still count and discard the skipped rows.

Senior engineers often prefer Cursor Pagination.

This method asks the database for “10 records starting after this specific ID.”

This utilizes database indexes efficiently and ensures that the query remains fast regardless of how much data exists. It also solves the problem of “drifting” results, where items might be skipped or duplicated if data is added while the user is scrolling.

7. Design for Idempotency

Network connections are unreliable.

A client might send a POST request to create an order, but the internet connection drops before the confirmation response is received.

The client, assuming the request failed, sends it again.

If the API is not Idempotent, the server will create two identical orders and charge the customer twice.

Idempotency guarantees that making the same request multiple times produces the same result as making it once.

To achieve this, the client generates a unique Idempotency Key for the transaction and sends it in the header.

The server checks a cache (like Redis) to see if it has already processed a request with that key.

If it has, it returns the stored response immediately without re-processing the logic. This mechanism ensures data integrity even in the face of aggressive retries and flaky networks.

8. Standardize Error Responses

Inconsistent error handling is a major source of frustration for frontend developers.

One endpoint might return a simple string when it fails, while another returns a JSON object, and a third just throws a generic 500 status code. This forces the frontend code to have complex, brittle logic to handle each case.

A senior engineer defines a Standard Error Schema. Every error response, regardless of the source, follows the same structure.

A robust error object typically includes:

• Code: A machine-readable string (e.g., INSUFFICIENT_FUNDS) that the frontend code can check against.
• Message: A human-readable description for the developer.
• Details: An optional field for validation errors (e.g., highlighting which specific form field was invalid).
• TraceID: The Correlation ID mentioned earlier, allowing support staff to look up the specific logs.

Standardizing this contract allows the client application to have a single, global error handler, simplifying development and maintenance.

9. Define Rate Limiting Strategies

Every system has a breaking point.

Without protection, a single malicious actor or simply a bug in a client script can send thousands of requests per second, overwhelming the database and taking the system offline for all legitimate users.

Rate Limiting controls the traffic flow. It restricts the number of requests a user or IP address can make within a specific time window (e.g., 60 requests per minute).

This behavior should be communicated clearly via HTTP headers:

• X-RateLimit-Limit: The maximum requests allowed.
• X-RateLimit-Remaining: The number of requests left in the current window.
• X-RateLimit-Reset: The timestamp when the window resets.

When a user exceeds the limit, the API returns a 429 Too Many Requests status. This protects the infrastructure and ensures fair usage across the user base.

10. Implement Caching Headers

Retrieving data from a database is an expensive operation in terms of CPU and I/O. Retrieving data from a local cache or a Content Delivery Network (CDN) is virtually instant.

A well-designed API utilizes HTTP Caching to reduce server load. By using the Cache-Control header, the API instructs the client (browser or mobile app) on how long to store the data.

For example, Cache-Control: max-age=3600 tells the client to use the cached version of the data for the next hour.

During this time, the client does not even contact the server. This dramatically improves the user experience by making the app feel faster and significantly reduces the cost of infrastructure by lowering the number of requests the backend must process.

Conclusion

Writing code is the visible part of software engineering, but it is the hidden work of design that determines success or failure.

The transition from junior to senior involves shifting focus from “getting it to work” to “keeping it working at scale.”

• Business Constraints prevent over-engineering.
• Contracts unblock teams and parallelize work.
• Backward Compatibility ensures long-term viability.
• Security and Observability protect the system and the data.
• Reliability mechanisms like Idempotency and Rate Limiting prepare the system for the real world.

By adhering to this checklist, engineers ensure that the code they eventually write is built on a foundation capable of supporting the business for years to come.