There is a specific kind of care that public APIs require that internal ones do not. When you ship an internal service, you are building for your team. When you ship a public API, you are building infrastructure that strangers will depend on. The standards are different (obviously).

The Cost of Inconsistency

I once spent five days integrating with an API that should have taken an afternoon. The problem was not complexity. It was chaos.

Some endpoints returned {data: [...]}. Others returned raw arrays. Field names varied: created_at, createdAt, creation_date. Pagination worked differently on every endpoint. There was no pattern to learn, no consistency to rely on. I could not build a mental model because there was no model to build.

When you cannot figure out how an API works by using it, integration becomes archaeology. You are constantly excavating documentation to discover how this specific endpoint behaves rather than applying what you learned from the last one.

Think about the difference between your internal tools and your user-facing product. Your internal tool might be a script that three people touch. Your product is polished, tested, and built for actual use. Public APIs deserve the same level of care as your product; they are your product.

Why This Matters

After integrating hundreds of services, you start to see patterns. The best APIs make integration feel effortless. The worst ones make you wonder if the company wants developers using their product. (BTW this doesn’t relate to the quality of the actual product. I’ve seen some great APIs from companies with terrible products and vice versa)

When a developer evaluates your API, they are asking: “How long will this take to integrate?”

Every inconsistent endpoint adds time. Every missing filter that forces workarounds adds time. Every surprise behavior that breaks their mental model adds time. Time is the only currency that matters.

Developers don’t integrate your API because they want to; they integrate your API because they need to. The faster they can get back to shipping features the better.

The difference between good and bad APIs is not technical sophistication. It is consistency and predictability.

Build a Boring API

Here is my proposal: build a boring API.

Not technically boring. Boring in the way a Honda Civic is boring. It is not exciting. It will not win design awards. But it starts every time, does exactly what you expect, and gets you where you need to go without drama.

Basic REST. Simple conventions. Nothing fancy. But it works, and it works the way developers expect.

The Core Principles

• Consistency over cleverness. Pick a pattern and stick to it everywhere. Use patterns that already exist and that people actually use. Same naming conventions, same response structures, same error formats. Your second endpoint should feel like your first. Developers will notice the pattern and build faster. And please just use REST.
• Convention over invention. There is a reason most REST APIs work similarly. Those patterns have been battle-tested by millions of developers. Use GET for reading, POST for creating, PATCH for updating (or PUT if that’s your thing). Return 200 for success, 404 for not found, 400 for bad input. Really basic stuff! These are not creative constraints, they are standards.
• Completeness over purity. Yes, technically you could make developers chain three requests to get the data they need. But should you? A good API includes sensible defaults, allows expanding related resources, includes enough data, and provides the filters people actually need. Do not make developers work around your API’s limitations.
• Errors are documentation. A good error message tells you exactly what went wrong and how to fix it. {"error": "Invalid request"} is useless. {"error": "Missing required field: email", "field": "email", "code": "missing_field"} is helpful. Your errors should teach developers how to use your API correctly.
• Predictability is a feature. When developers can guess how your API works and be right, that is not boring. That is perfect. It means you have built something that matches their mental model so well they do not need to constantly check the docs.

If you are reading this and think: “yeah obviously”. You’re right, it should be obvious. But looking at many public APIs is simply isn’t.

Why Boring Wins

Stripe’s API is boring in the best way. So is WorkOS’s. They are not trying to reinvent REST or introduce novel patterns. They just implement the standard approach well.

APIs that try to be clever, that reinvent conventions, that do things differently because they can, those are the ones that waste developer time. They are the ones where integration takes days instead of hours. They are the ones developers actively complain about.

Boring does not mean limited.

A boring API can be powerful. Webhooks, bulk operations, real-time updates, sophisticated filtering are all fair game. The boring part is not about features. It is about design.

The Bottom Line

Public APIs are infrastructure. They are not your chance to be creative with response structures or reinvent how pagination works. They are meant to be reliable, predictable, and boring.

Save your innovation for your product. Let your API be boring.

Developers do not want to integrate with your API. They want to build something using your API. The faster they can stop thinking about your API and start building their thing, the better you have done your job.

If your thought after reading this article is “yeah, duh!”. You’re not the problem. But many devs building public APIs (or more likely their managers) are.

Building something with AI? Check out Metorial. We make it dead simple to integrate 600+ tools with your agents. Open source, great SDKs, and actually maintained by people who understand infrastructure.