APIs should solve problems, not be the problem — core principles, HTTP standards, and developer experience.
Do your APIs solve your problems or create them? What is 200 OK and when should it be used? Let's say up front what we'd say at the end.
Is the following correct? We say no: returning 200 OK for a response that contains an error goes against API design standards. This doesn't only affect API design; it can trigger many issues in system architecture.
For example, monitoring products usually treat 2xx responses as success. If 200 OK doesn't actually mean success, monitoring must look at message content as well as status codes, which leads to potential issues and observability problems.
Especially when you share data with external partners via APIs, APIs are not just technical interfaces — they are your products, and developers are your customers.
A good API Program Manager / Product Manager / Developer Advocate lives by this mantra:
"APIs should help you solve your problems. APIs should not be your problem." — David Biesack
APIs are the bridges through which software systems communicate, share data, and work together. A well-designed API makes interaction easy; a poorly designed one creates complexity and trouble. APIs are your products; developers are your customers.
Core principles for the API team
"We design our API from the developer's perspective" sounds simple, but in practice many teams say it without fully living it. Here are the core principles.
1. Developer experience (DX) comes first
Design APIs from the developer's point of view. They are your customers; you must deliver a good customer experience.
Ask yourself: How easy is your API to understand? Is the documentation clear? Is usage intuitive?
Common pitfall: complex authentication and authorization. Even standards like OpenID Connect or OAuth 2.0 can be tough for developers without the right libraries.
Practical solution: offer quick-start guides, simple auth options, sandbox environments, and step-by-step visual guides for the auth flow.
2. Simplicity and clarity are key
Complex APIs waste time, increase errors, and frustrate developers. A good API does the most with the least effort.
Common pitfall: exposing database schemas or internal system structures as-is.
Practical example: use real booleans instead of "Y" / "N"; use
meaningful strings or enums instead of opaque integer codes.
Strong solution: use JSON Schema to define fields, required fields, and formats clearly. Expose a clean model that matches your API's purpose.
3. Consistency is essential
Naming conventions, response formats, parameter structures, and error messages should be standard and predictable. Inconsistency erodes trust.
Common pitfall: ignoring HTTP semantics — returning 200 for errors instead of 4xx / 5xx; using 200 instead of 201 Created for POST; unsafe / non-idempotent GETs; not using standard headers like Location and Retry-After.
Strong solution: create an API Style Guide; reference Arnaud Lauret's "five dimensions of API consistency" and follow HTTP semantics.
4. Reliability and performance are non-negotiable
An API must respond quickly and run reliably. A slow or constantly failing API drives developers to other solutions.
Common pitfall: not thinking about error handling from the start.
Strong solution: plan how you'll handle errors; use standard error
formats like application/problem+json; provide clear, actionable
messages; identify and optimize bottlenecks early; run load tests and
plan capacity.
5. Design with the future in mind (evolution)
APIs change over time. The design should be extensible, preserve backward compatibility, and adapt to future changes.
Common pitfall: designing the API so it can't evolve, or assuming
that changing the version in the URL (/v1/ → /v2/) is enough.
Strong solution: use API Design and Documentation Review (ADDR) processes; model use cases in advance; reserve versioning for major changes; make small changes in a backward-compatible way; roll out gradually.
6. Open communication and transparency
Planned changes, new releases, and deprecations should be announced proactively and clearly; feedback channels should be open.
Practical solution: maintain a detailed changelog; announce upcoming changes in advance; allow a transition period for deprecated features; provide forums or community channels; run regular webinars and training.
What successful APIs have in common
- They state their purpose clearly
- They rest on a clear conceptual model
- They serve user needs instead of reflecting internal system structure
- They follow standards, especially HTTP semantics
- They behave in ways developers can predict
- They handle error cases effectively
- Their evolution is planned from the start
Common mistakes and fixes
| Mistake | Result | Fix |
|---|---|---|
| Returning 200 OK for errors | Observability issues | Use appropriate HTTP status codes (4xx, 5xx) |
| Complex authentication | Integration difficulty | Offer simple, standard auth mechanisms |
| Inconsistent naming | Inconsistent codebases | Create an API Style Guide and stick to it |
| Mirroring database structure | Unnecessary complexity | Design clean models aligned with business goals |
| No evolution plan | Version chaos | Design for extensibility from the start |
Living the mantra
APIs are not just pieces of code; they are strategic business assets. A successful API program puts developers at the center, makes their job easier, and produces simple, consistent, reliable, and forward-looking designs.
By embracing "APIs should solve your problems, not be your problem" and applying the principles above, you can build APIs developers love and that serve your business goals.
Most important steps:
- Follow HTTP standards
- Return meaningful error codes
- Continuously improve developer experience