After reviewing hundreds of API designs over my career — for clients, open source projects, and my own work — certain mistakes keep appearing. These aren’t obscure edge cases. They’re fundamental design choices that seem reasonable at first but create real problems as your API grows.

Mistake 1: Inconsistent Naming

This sounds trivial, but inconsistent naming is the most common issue I see. An API that uses userId in one endpoint, user_id in another, and UserID in a third is painful to consume. Pick a convention — camelCase for JSON is the most common in JavaScript ecosystems, snake_case is standard in Python and Ruby — and enforce it everywhere.

The same applies to endpoint naming. If you have /api/users for listing users, don’t create /api/getProducts for listing products. Consistency matters more than any individual naming choice.

Mistake 2: Not Versioning From Day One

“We’ll add versioning when we need it” is a statement that precedes breaking every client integration simultaneously. Version your API from the first release. Whether you use URL path versioning (/api/v1/users), header versioning, or query parameter versioning doesn’t matter much. What matters is that the mechanism exists before you have external consumers.

URL path versioning is the most visible and easiest to implement. Header-based versioning is “cleaner” from a REST purist perspective but harder to test in a browser. I default to URL path versioning unless there’s a specific reason not to.

Mistake 3: Returning Too Much Data

The default response for a “get user” endpoint should not include every field in the database. Over-fetching wastes bandwidth, exposes internal data structures, and creates implicit contracts that make future changes difficult.

Design your default responses to include only what a typical consumer needs. Provide field selection mechanisms — query parameters like ?fields=name,email or GraphQL’s built-in field selection — for consumers who need more or less data.

This is especially important for list endpoints. Returning full user objects for a list of 1,000 users when the consumer only needs names and IDs is wasteful and slow.

Mistake 4: Ignoring Pagination

Every list endpoint needs pagination from day one. “We only have 50 records” is true until it isn’t, and adding pagination to an existing endpoint is a breaking change.

Cursor-based pagination is superior to offset-based for most use cases. Offset pagination breaks when records are inserted or deleted between requests. Cursor pagination is stable, faster for the database, and works naturally with infinite scroll UIs.

{
  "data": [...],
  "pagination": {
    "next_cursor": "abc123",
    "has_more": true
  }
}

Mistake 5: Poor Error Responses

An error response of {"error": "Bad Request"} tells the consumer nothing useful. Good error responses include:

• A machine-readable error code
• A human-readable message
• The field or parameter that caused the error (for validation errors)
• A link to documentation when relevant

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The email field must be a valid email address",
    "field": "email",
    "docs": "https://api.example.com/docs/errors#VALIDATION_FAILED"
  }
}

Use appropriate HTTP status codes. 400 for client errors, 401 for authentication failures, 403 for authorization failures, 404 for missing resources, 422 for validation errors, 500 for server errors. Don’t return 200 with an error message in the body.

Mistake 6: No Rate Limiting

If your API is accessible over the internet, it needs rate limiting. Without it, a single misbehaving client can degrade service for everyone. A buggy script in an infinite loop will find your unprotected endpoint at 3 AM.

Implement rate limiting early and return proper headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) so clients can self-regulate. Return 429 Too Many Requests when limits are exceeded.

Mistake 7: Authentication as an Afterthought

I’ve consulted on projects where the API was built entirely without authentication, with plans to “add it later.” Retrofitting authentication into an existing API is painful. Every endpoint needs to be audited, tested, and updated. Clients need to modify every request.

Many teams working with business AI solutions providers find that API security is the first thing that needs addressing when integrating AI capabilities into existing systems. Getting authentication right from the start saves significant rework.

Use established standards. OAuth 2.0 for third-party access, API keys for server-to-server communication, JWTs for session management. Don’t invent your own authentication scheme.

Mistake 8: Ignoring CORS

If your API will be consumed from a browser, configure CORS properly from the start. The default browser behaviour is to block cross-origin requests, and debugging CORS issues is one of the most frustrating developer experiences.

Set specific allowed origins rather than using *. Configure allowed methods and headers explicitly. Handle preflight requests correctly.

The Common Thread

Most of these mistakes share a root cause: optimising for the speed of initial development at the expense of long-term usability. An API is a contract with your consumers. Breaking that contract — through inconsistency, missing features, or poor error handling — erodes trust and creates support burden.

Spend the extra day getting these fundamentals right. Your API consumers, including your future self, will thank you.