Stop Cargo Culting REST: Most “RESTful” APIs Aren’t Worth the HTTP Status Code They’re Printed On
Let me start with a confession that might get me kicked out of the senior engineer club: most APIs I encounter in the wild that claim to be RESTful are about as RESTful as a NASCAR race. They slap HTTP verbs on everything, return JSON, and call it a day. The real tragedy isn’t that they’re not following Roy Fielding’s dissertation to the letter, it’s that they’re missing the actual value proposition of REST while cargo culting the surface-level mechanics.
The constraint that actually matters in REST is the uniform interface, specifically the idea that resources should be manipulable through representations. When your “RESTful” API requires clients to POST to `/api/v1/users/123/activate` instead of PATCH-ing the user resource with `{“status”: “active”}`, you’ve missed the point entirely. You’re just doing RPC with extra steps and a superiority complex.
Here’s what I’ve learned after debugging too many integration failures at ungodly hours: consistency beats purity every time. If you’re going to build an HTTP-based API, pick a pattern and stick to it religiously. Whether that’s resource-oriented design, action-oriented endpoints, or some hybrid approach doesn’t matter nearly as much as whether your team can implement it consistently across 200+ endpoints without losing their minds.
The most successful API I ever worked on broke half the REST principles but followed the other half with obsessive precision. Every resource had a canonical URL structure, every response included proper cache headers, and every error was mapped to an appropriate HTTP status code. The frontend team loved us because they never had to guess how an endpoint would behave. That’s worth more than any architectural purity points.
Pagination: The Feature Everyone Implements Wrong Until Production Melts
Offset-based pagination is the programming equivalent of technical debt you inherit from your past self who thought 10,000 records was “a lot of data.” You know the pattern: `?page=1&limit=20`, `?offset=100&limit=20`. It feels intuitive, maps nicely to SQL LIMIT/OFFSET, and works beautifully until someone tries to paginate through your entire user table and your database starts crying.
The problem isn’t just performance, though watching `OFFSET 1000000` execute is its own special form of torture. The real issue is consistency. While your client is paginating through results, records are being added, updated, and deleted. That user who signs up on page 47 might show up on page 46 by the time the client gets there. Or disappear entirely if they’re unlucky enough to land on the boundary of a page shift.
Cursor-based pagination solves this elegantly, but everyone thinks it’s “too complicated” until they’re explaining to leadership why the analytics dashboard is showing duplicate users. The pattern is straightforward: return a cursor with each page of results, use that cursor as the starting point for the next page. Your cursor can be a timestamp, an ID, or any stable, sortable field that makes sense for your data.
Here’s the implementation reality check: cursor-based pagination requires you to think about your data access patterns upfront. You can’t just slap it onto an existing endpoint that sorts by three different fields depending on query parameters. This is a feature, not a bug. It forces you to design APIs that can actually scale instead of deferring the hard decisions until your monitoring starts sending angry alerts.
Error Handling: Where Good APIs Go to Die
Nothing reveals the maturity of an API faster than how it handles errors. I’ve seen production APIs that return HTTP 200 with `{“success”: false, “error”: “User not found”}` and APIs that throw HTTP 500 when you send an empty request body. Both approaches demonstrate a fundamental misunderstanding of what HTTP status codes are for and why your monitoring system exists.
The correct approach isn’t complicated, but it requires discipline. Use HTTP status codes for what they’re designed for: indicating the class of response. 4xx for client errors, 5xx for server errors, 2xx for success. Then use your response body to provide the specific details. When someone sends malformed JSON, return 400 with details about what was malformed. When your database is down, return 503 and let your load balancer route around the problem.
Error response structure matters more than you think. Pick a format and stick to it everywhere. I prefer something like `{“error”: {“code”: “VALIDATION_FAILED”, “message”: “User validation failed”, “details”: [{“field”: “email”, “issue”: “Invalid format”}]}}` but the exact schema is less important than consistency. Your SDK authors will thank you when they can write error handling code once instead of custom logic for every endpoint.
The hardest part of error handling isn’t the technical implementation, it’s resisting the urge to expose internal implementation details when things go wrong. Your clients don’t need to know that the failure happened in `UserService.validateEmail()` line 47. They need to know that the email format was invalid and how to fix it. Save the stack traces for your logs.
Versioning: The Necessary Evil Everyone Overthinks
API versioning discussions tend to devolve into religious wars between the URL prefix zealots (`/v1/users`), the header purists (`Accept: application/vnd.api+json;version=1`), and the query parameter pragmatists (`?version=1`). Meanwhile, the real question gets lost in implementation bikeshedding: how do you evolve an API without breaking existing clients?
Here’s what actually matters: can you deploy a breaking change without coordinating releases across 15 different client applications? If the answer is no, your versioning strategy is irrelevant because you’ll never use it. The most elegant versioning scheme in the world is useless if your deployment process requires three different teams to coordinate releases during a maintenance window.
Semantic versioning works well for APIs, but only if you’re honest about what constitutes a breaking change. Adding optional fields to responses? Not breaking. Removing fields? Breaking. Changing field types? Breaking. Making previously optional fields required? Very breaking. The key is documenting these rules and actually following them, not discovering your interpretation of “backward compatible” differs from your clients’ when the Slack alerts start firing.
The dirty secret of API versioning is that most successful APIs avoid it through careful design rather than clever implementation. Additive changes, feature flags, and progressive enhancement patterns let you evolve APIs without the complexity of maintaining multiple versions. When you do need versioning, the simplest approach that works for your deployment constraints is usually the right choice.
I’ve spent more time than I care to admit wrestling with these patterns in production environments where theory meets the brutal reality of user expectations and SLA requirements. What patterns have you found that actually hold up under production load? I’m particularly curious about cursor-based pagination implementations that handle high-write scenarios gracefully. Drop your experiences in the comments or send them my way on email.