DEV Community

Tyson Cung
Tyson Cung

Posted on

Why Most APIs Fail — 3 Mistakes That Kill Developer Experience

#api #softwareengineering #programming #webdev

I've integrated hundreds of APIs over the years. Some were a pleasure. Most were a chore. A handful were genuinely painful experiences that made me question the life choices that led me to this career.

The frustrating part: the same three mistakes show up over and over. They're not exotic bugs. They're design decisions that seemed fine at the time and became load-bearing walls of confusion later.

Mistake 1: Inconsistent Naming

This sounds trivial. It isn't.

I once integrated with an API where the user ID was called userId in the auth endpoints, user_id in the profile endpoints, and uid in the events endpoints. Same field. Three names. Zero documentation explaining why.

Inconsistent naming forces developers to check the docs for every single call. It breaks the intuition that good APIs build — the feeling that you can guess what a field is called because everything follows the same pattern.

The fix is boring: pick a convention (camelCase, snake_case, kebab-case — doesn't matter which) and use it everywhere. Make a linter rule if you have to. Never let "we just called it something different here" ship to production.

Bonus failure mode: Naming things what they are today, not what they'll need to be. isAdmin becomes a lie the moment you add a second role type. premiumUser breaks when you launch three tiers. Use abstract names that survive your roadmap.

Mistake 2: No Versioning

Every API will change. If you're not versioning, you're setting up for one of two bad outcomes:

  1. You never change anything because you're afraid of breaking integrations (stagnation)
  2. You change things and break integrations (chaos)

Versioning buys you the ability to evolve without punishing your existing users. /v1/users stays stable. /v2/users adds the new fields. Clients migrate on their schedule, not yours.

The most common excuse for not versioning: "We'll add it when we need it." By the time you need it, you have production clients that assume the unversioned endpoint is permanent. Adding a version prefix to existing routes is a breaking change. You've trapped yourself.

Start with versioning. Even if v1 never changes, having the habit in place means v2 doesn't cause a crisis.

URL vs Header versioning: Both work. URL (/v1/endpoint) is more visible and easier to debug. Header versioning (Accept: application/vnd.api+json;version=2) is cleaner architecturally but harder to test in a browser. Pick one and document it clearly.

Mistake 3: Poor Error Responses

This is the one that makes me lose my mind most often.

{"error": "Something went wrong"}
Enter fullscreen mode Exit fullscreen mode

That's not an error response. That's an apology. It tells me nothing I can act on.

A good error response tells me:

  • What went wrong (specific, not generic)
  • Why it went wrong (validation failure? rate limit? bad auth?)
  • What I can do about it (retry? fix the request? check my credentials?)

The gold standard:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'email' field must be a valid email address",
    "field": "email",
    "docs": "https://api.example.com/docs/errors#VALIDATION_ERROR"
  }
}
Enter fullscreen mode Exit fullscreen mode

I can read that, understand it, and fix my request without a support ticket.

Also: use the right HTTP status codes. 200 OK with an error body is a crime against HTTP. 401 vs 403 is not interchangeable. 404 vs 410 (gone vs not found) matters for caching behavior. These distinctions exist for a reason — use them.

The Real Cost of Getting This Wrong

Bad API design doesn't just frustrate developers. It costs you:

  • Support time — most support tickets are "what does this error mean" or "where is this field"
  • Integration time — slow, painful integrations mean fewer third-party developers bother
  • Churn — if your API is harder than a competitor's, the technical buyer notices

The best APIs are the ones where developers get to the first successful call in under 10 minutes. That's the goal. Consistent naming, versioning from day one, and real error responses get you most of the way there.

The boring stuff is usually the most important.

Which API gave you the worst integration experience? I want to hear the horror stories.

Top comments (0)