The REST Orthodoxy Is Making Your API Worse
We need to talk about REST. Not the philosophical ideal of REST that Roy Fielding described in his dissertation, but the cargo-cult version that most teams implement. You know the one: slap HTTP verbs on everything, call it RESTful, and ship it. I’ve spent the last decade watching teams contort themselves into pretzels trying to force every operation into GET/POST/PUT/DELETE, creating APIs that are technically RESTful but practically useless.
The real problem isn’t REST itself. It’s the religious adherence to REST principles even when they don’t fit your use case. Take batch operations. I’ve seen APIs that require 47 individual DELETE requests to clean up a user’s data because “that’s the RESTful way.” Meanwhile, your mobile app times out, your database connection pool explodes, and your users wonder why your competitor’s app feels so much snappier.
Modern API design recognizes that different problems need different solutions. GraphQL handles complex data fetching elegantly. gRPC excels at high-performance service-to-service communication. Even good old RPC-style endpoints can be the right choice for operations that don’t map cleanly to resource manipulation. The best APIs I’ve worked with in the last few years use REST as a starting point, not a straightjacket.
Your Error Handling Is Probably Terrible
Let’s conduct a quick audit. When your API returns a 400 Bad Request, what information does the client actually get? If the answer is a generic error message that could apply to any validation failure, you’re doing it wrong. I’ve debugged too many integration issues where the only clue was “Invalid input” and a prayer to the logging gods.
Good error handling follows a simple principle: give developers exactly what they need to fix the problem without exposing internal implementation details. This means structured error responses with specific error codes, clear descriptions, and actionable guidance. When a required field is missing, tell them which field. When a value is out of range, tell them the valid range. When rate limiting kicks in, tell them when they can try again.
The RFC 7807 Problem Details specification provides a solid foundation, but don’t treat it as gospel. What matters is consistency across your API and usefulness to your consumers. I’ve seen teams spend weeks arguing over the perfect error schema while their API returns HTTP 200 with error messages buried in JSON. Perfect is the enemy of good, but good is still better than whatever that is.
Pagination: Where Good Intentions Go to Die
Here’s a fun exercise: count how many different pagination schemes you’ve encountered in the last year. Offset-based, cursor-based, page-based, limit-skip, next-previous tokens. The pagination world looks like a standards committee explosion, and most implementations have subtle bugs that only surface when someone actually tries to paginate through large datasets.
Offset-based pagination feels intuitive but breaks down at scale. Ever notice how Google search results get weird after page 20? That’s because offset pagination becomes expensive and inconsistent as you go deeper into large datasets. Meanwhile, your API is probably using OFFSET/LIMIT queries that get slower with each page and can return duplicate results if data changes during pagination.
Cursor-based pagination solves the performance problem but creates a usability problem. Clients can’t jump to arbitrary pages, can’t show meaningful progress indicators, and debugging becomes harder when cursors are opaque tokens. The solution isn’t to pick one approach and use it everywhere. Design your pagination strategy based on how your API actually gets used. Real-time feeds need cursor pagination. Administrative interfaces often need offset pagination. Some endpoints need both.
The Versioning Trap Everyone Falls Into
API versioning strategies generate more heated debates than text editors, and most of them miss the fundamental point. Versioning isn’t about picking the perfect scheme. It’s about minimizing the pain of change for both API providers and consumers. Yet teams regularly choose versioning approaches that maximize complexity while providing minimal flexibility.
URL versioning (/v1/users) is visible and explicit but couples versioning to routing infrastructure. Header versioning keeps URLs clean but makes testing and debugging harder. Media type versioning is theoretically elegant but practically ignored by most tooling. Each approach has genuine trade-offs, but the choice matters less than having a clear deprecation policy and migration path.
The real versioning trap is thinking you can avoid breaking changes through clever design. You can’t. Requirements evolve, security issues surface, and performance constraints force architectural changes. The APIs that age well plan for change from the beginning. They use explicit contracts, maintain backward compatibility where possible, and communicate breaking changes clearly with sufficient lead time.
Authentication: Beyond the Bearer Token Cargo Cult
Every API tutorial starts with JWT bearer tokens, so every API ends up using JWT bearer tokens. Never mind that JWTs are stateless tokens optimized for distributed systems, while your monolithic API could benefit from simple session tokens with server-side revocation. Never mind that storing sensitive claims in JWTs creates security risks that most teams don’t understand.
The choice between different authentication schemes should be driven by your actual requirements, not by what’s trendy. Do you need single sign-on across multiple services? JWTs make sense. Do you need fine-grained permission revocation? Server-side sessions are simpler. Do you have mobile clients with intermittent connectivity? Consider the token refresh workflow carefully.
More importantly, authentication is just the first step. Authorization is where most APIs fall apart. Role-based access control sounds simple until you have 47 different roles and nobody remembers what the “content_moderator_regional” role actually does. Attribute-based access control is theoretically powerful but practically complex to implement and debug. The authorization scheme that works is the one your team can reason about correctly under pressure at 3 AM.
What patterns have you seen work well in practice? I’m particularly interested in how teams handle the inevitable evolution from simple authentication to complex authorization requirements without rewriting everything. The comment section is open, and unlike most APIs, it actually works reliably.