Your REST API is Leaking : Here’s How to Plug Every Hole
Every junior developer can spin up an Express server and return some JSON. But there’s a massive gap between “works on my machine😂” and “ready for production.”
I spent today deep-diving into REST API design standards — the kind used by Stripe, Twitter, GitHub, and Slack. Here’s everything I learned, with real examples and the “why” behind every decision.
By the end of this article, you’ll understand how to design APIs that are clean, scalable, and a joy to use.
1. URL Design: Nouns, Not Verbs
The most fundamental rule of REST API design is deceptively simple: your url should describe resources, not actions. The HTTP method carries the action.
This means no verbs in your URLs. Ever.
— The right way:
— The wrong way:
The nested route — /users/:id/orders isn’t just aesthetic. It communicates a real ownership relationship. Orders belong to users. The URL encodes your data model.
INTERVIEW TIP
When asked about REST, always explain the resource-vs-action distinction. Then demonstrate that you know the difference between PUT (full replace) and PATCH (partial update). Most candidates confuse these.
2. API Versioning: Never Break Your Clients
APIs evolve. New fields get added, old endpoints get deprecated, business logic changes. Without versioning, any update you push could silently break thousands of clients that depend on your current behavior.
There are two main approaches:
— URL Versioning (recommended)
GET /api/v1/users
GET /api/v2/users
- simple and immediately visible.
- works perfectly with browser testing and curl.
- CDN caching works naturally.
- Easy to depricate, just sunset /v1 after a notice period.
- Used by : stripe, twilio , github.
— Header Versioning
Accept: application/vnd.api+json; version=2
X-Api-Version: 2
- cleaner URLs.
- Harder to test directly in browser.
- Requires client awareness to set the header correctly.
- Used by: Github(for some endpoints).
URL versioning wins for most teams because it’s the most debuggable. When something breaks, you can paste the URL in a browser and reproduce it immediately.
3. Pagination: Why Your Page=3 Is Lying to You
Pagination is where beginner APIs reveal themselves. Most developers reach for the obvious solution first. It seems fine until you hit production.
Get Anurag Rajput’s stories in your inbox
Join Medium for free to get updates from this writer.
— Offset Pagination (simple but broken)
GET /api/posts?page=3&limit=20
— SQL
SELECT * FROM posts LIMIT 20 OFFSET 60
The fatal flaw: what happens if someone inserts a new post while a user is paginating through results? Every row shifts. The user on page 3 either sees a duplicate from page 2, or skips a row entirely. This is a silent bug that plagues most production APIs.
— Cursor Pagination (the production standard)
Cursor pagination is anchored to the last item you saw, not a row count. New inserts don’t affect your position. Results stay consistent even under heavy write load.
This is why Twitter, Instagram, and Slack all use cursors. At scale, it’s not optional.
4. Error Responses: The Part Nobody Thinks About
Good error responses are a form of respect for the developers using your API. A vague 400 with no body is the equivalent of a door slamming in someone’s face.
Here’s the standard error format used in production systems:
Let’s break down why each field matters:
1.code — machine-readable, an enum your frontend can switch on programmatically.
2. message — human-readable, safe to display in a UI.
3. details — per-field issues, so the frontend knows exactly which input is broken
4. requestId — THIS IS THE MOST IMPORTANT FIELD.
5. timestamp — useful for log correlation across systems
6. docs — links the developer directly to the fix
Why requestId is non-negotiable-
When a user screenshots an error and sends it to support, you grep your logs for the requestId and instantly find the exact stack trace, the full request payload, the user ID, the database query everything. Without it, debugging production errors is archaeology. With it, it’s a 10-second lookup.
Putting it all Together
REST API design is one of those skills that looks simple from the outside but has enormous depth. The difference between a junior and senior backend developer often shows up in exactly these four areas: URL structure, versioning discipline, pagination strategy, and error quality.
These aren’t just interview topics they’re the decisions that make or break the developer experience for everyone who uses your API.
If you’re learning backend development for placements, focus here. These are the questions interviewers ask because they reveal whether you understand the production implications of your choices, not just the happy path.
Happy building — and ship clean APIs.
