Why Consumers Should Lead API Design: Lessons from Real-World Mistakes

Who Should Lead API Design

Should the consumer or the provider decide how an API is designed? Obviously the consumer.

The most paradoxical aspect of an API is that the provider spends a lot of effort implementing it, yet rarely uses it themselves, leading to designs that are hard for consumers to call and hard for providers to maintain.

Example 1: Chatty API

A feature that creates a dashboard page required two sequential calls: first create an empty dashboard with basic info, then populate it with chart details. This design mirrors the backend storage structure and forces the frontend to understand internal data models.

Create an empty dashboard using user‑provided basic info and chart layout.

Fill the dashboard with specific chart data such as type, dimensions, and metrics.

When the underlying storage changes, the API must change, and the frontend code must be updated accordingly. Some backend engineers justify this by pointing to micro‑services, but the fragmentation of the API is a problem that should not be shifted to the frontend.

Daniel Jacobson notes that APIs serve two audiences: LSUD (large set of unknown developers) and SSKD (small set of known developers). Exposing internal service details to LSUD is risky.

Example 2: Meta Information

Backend APIs often return a meta field containing status and error details:

{
  "meta": {
    "code": 0,
    "error": null,
    "host": "127.0.0.1"
  },
  "result": []
}

This design raises two issues:

Do we really need a parallel meta field for every response?

Should meta data always be nested under meta?

Often the HTTP status code already conveys success or failure, making a custom meta.code redundant. Critical meta can be moved to HTTP headers (e.g., X‑RateLimit‑Limit in GitHub API).

Design for Today

Example 3: Batch Article Request

Instead of returning articles grouped by entity, the API should return data per article:

{
  "articles": [
    {"id": ..., "author": {}, "comments": []},
    {"id": ..., "author": {}, "comments": []}
  ]
}

Returning flat lists forces the frontend to regroup data, adding unnecessary processing.

Example 4: Single‑Day Query

Even when a query is guaranteed to return data for a single day, some backends still wrap the result in an array to anticipate future multi‑day requests, leading to over‑engineering.

Example 5: Bulk Create vs. Repeated Single Create

Calling a single‑item creation endpoint repeatedly is not equivalent to a true bulk‑create operation, which may require transactional guarantees and preserve order.

Example 6: Reusing Article API for User Info

Using an existing article endpoint to fetch user information is a hack rather than proper reuse; it couples unrelated concerns and risks breaking when the article schema changes.

Each of these cases illustrates why an API should focus on a single responsibility and avoid unnecessary abstraction.

Beyond REST APIs

While REST is the dominant style, other protocols can be more suitable for specific scenarios. Real‑time updates benefit from WebSocket or streaming, backend‑to‑backend interactions can use WebHooks, and GraphQL can simplify complex data fetching.

Even though API implementation is a small part of backend work, investing effort to make interfaces clear, stable, and consumer‑driven pays off in long‑term maintainability.

Conclusion

Bad API designs cause friction for both providers and consumers. Simple, consumer‑oriented principles—such as letting the consumer dictate the contract, keeping responses precise, and exposing only necessary meta—can dramatically improve developer experience and product quality.