The REST Cargo Cult Has Gone Too Far

Let’s address the elephant in the room first. Half the “RESTful” APIs I’ve encountered in production wouldn’t know Roy Fielding’s dissertation if it walked up and introduced itself. We’ve collectively decided that slapping HTTP verbs onto CRUD operations makes us architectural purists, while ignoring the actual constraints that make REST useful.

The real crime isn’t violating REST principles. It’s the mindless following of patterns that don’t serve your use case. I’ve seen teams twist their domain models into resource hierarchies that would make a yoga instructor weep, all because someone read that URLs should be “noun-based.” Meanwhile, their API users make six round trips to accomplish what should be a single operation.

GraphQL emerged precisely because REST’s resource-focused approach often clashes with how applications actually consume data. But instead of learning from this, we double down on REST orthodoxy. The result? APIs that are “correct” by some arbitrary standard but painful to use in practice.

Pagination: Where Most APIs Go to Die

Nothing exposes sloppy API design quite like pagination. The number of production APIs I’ve seen that return unbounded result sets is genuinely alarming. Your database will eventually buckle under the weight of that SELECT * FROM users query. When it does, your API will take the entire application down with it.

Offset-based pagination seems intuitive until you realize it creates a consistency nightmare. Users navigate to page 47 of search results just as new records get inserted at the top. Suddenly they’re seeing duplicate items across page boundaries, wondering if your API is having an existential crisis. Spoiler alert: it is.

Cursor-based pagination solves the consistency problem elegantly. Each page token represents a stable point in your dataset, making navigation predictable even as data changes underneath. Yes, it’s slightly more complex to implement. Yes, it’s worth it. The alternative is fielding support tickets from confused users who swear they’ve seen the same product listing three times.

The real pagination winners use keyset pagination with meaningful cursors. Instead of opaque tokens, expose the actual sort key. If you’re sorting by creation timestamp, let the cursor be that timestamp. Your API becomes self-documenting, and debugging becomes trivial when someone reports weird pagination behavior.

Error Handling: Beyond the HTTP Status Code Theater

HTTP status codes are necessary but not enough for meaningful error handling. Returning a 400 Bad Request with no additional context is the API equivalent of your car’s check engine light. Technically informative, practically useless.

The pattern that consistently works in practice combines HTTP semantics with structured error responses. Use the status code to indicate the general category of failure, then provide machine-readable error codes and human-friendly descriptions in the response body. Your API clients can handle known error scenarios programmatically while still giving users meaningful feedback.

Error codes should be stable and documented. I’ve seen APIs where the same validation failure returns different error messages depending on which engineer was on call when the code was written. This creates an integration nightmare where client applications can’t reliably detect and handle specific error conditions.

Field-level validation errors deserve special attention. When a request fails validation on multiple fields, return all the errors at once. Nothing frustrates developers more than fixing one validation error only to discover three more lurking behind it. Structure these errors consistently with field names, error codes, and descriptions. Your future self will thank you when you’re debugging a failed integration at midnight.

Versioning: The Necessary Evil We Keep Getting Wrong

API versioning is where good intentions go to die. The theoretical elegance of semantic versioning crashes into the reality of backward compatibility and client upgrade cycles. I’ve seen teams tie themselves in knots trying to maintain five simultaneous API versions because they promised eternal backward compatibility.

URL versioning gets mocked by purists, but it works reliably in practice. Clients explicitly declare which version they expect, making compatibility issues immediately obvious. Compare this to header-based versioning, where a misconfigured client silently receives the wrong API version and nobody notices until something breaks spectacularly in production.

The versioning strategy that survives contact with reality involves planned obsolescence from day one. Set deprecation timelines upfront and communicate them clearly. Give clients enough notice to migrate, but don’t promise to maintain ancient versions forever. Your API will evolve, and trying to freeze it in amber helps nobody.

Rate Limiting: Your First Line of Defense Against Reality

Rate limiting isn’t just about preventing abuse. It’s about maintaining service quality when reality inevitably differs from your capacity planning assumptions. That innocent-looking API endpoint will eventually get hammered by a poorly configured client loop. Without rate limiting, your entire service becomes collateral damage.

Token bucket algorithms provide the smoothest user experience for legitimate traffic while still preventing abuse. Unlike fixed window rate limiting, token buckets allow brief bursts of activity followed by natural cooling-off periods. This matches how real applications actually behave much better than artificial per-minute quotas.

The key insight most teams miss is that different endpoints need different rate limiting strategies. Your authentication endpoint should be much more restrictive than your data retrieval endpoints. User-specific operations might have per-user limits while system-wide operations need global throttling. One-size-fits-all rate limiting creates unnecessary friction for normal usage while failing to prevent actual abuse scenarios.

What patterns have shaped your API design philosophy? I’m particularly interested in hearing about the disasters that taught you what not to do. The best engineering lessons always come with battle scars attached.