A bad API is like a bad neighbor. It makes everyone’s life harder, and you can’t get away from it.

I’ve reviewed hundreds of APIs over my career, and the difference between “fine” and “delightful” usually comes down to a few simple decisions made early.

Naming: Be Explicit

Bad: /api/get

Good: /api/v1/users/123

Your API consumers should understand what they’re calling just from reading the path. RESTful conventions exist for a reason—use them:

• GET for retrieving data
• POST for creating
• PUT/PATCH for updating
• DELETE for removing

Versioning: Plan for Growth

Start with v1, even if you’re the only consumer. Trust me, you’ll thank yourself later.

/api/v1/users vs /api/v2/users

This is so simple, but it saves you from breaking everyone’s integrations when you need to make a breaking change.

Error Handling: Be Consistent

Every error response should include:

• Status code: 400 for client errors, 500 for server errors
• Error message: Clear explanation of what went wrong
• Error code: Machine-readable identifier (not just the message)
• Details: Specific information that helps debugging

{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "The provided email is not valid",
    "details": {
      "field": "email",
      "value": "not-an-email"
    }
  }
}

Documentation: Your API’s Real Contract

Write documentation first. If you can’t explain it clearly, the API is too complex.

Your documentation should include:

• Every endpoint and what it does
• Required and optional parameters
• Example requests and responses
• Common errors and how to handle them
• Authentication requirements

Use OpenAPI/Swagger. It’s the standard, and tools can generate client libraries from it.

Good APIs don’t just work—they feel good to use. That feeling comes from someone caring about the developer experience.