Eight of the Biggest Lies in APIs

Have you ever been told "Everybody does it this way" when arguing about API design? Or have you heard, "We use HTTPS, so our API is secure"?

In the API space, numerous statements are highly context-dependent, misunderstandings, or outright lies. To find some of the most egregious of these, I asked the APIs You Won't Hate Slack for those phrases that stand their neck hair on end and their eyes to see red. If you find yourself about to use one of these jargon phrases unironically in your next architectural debate, please think twice.

These are The Eight Greatest API Lies, as sourced from the community:

8. It's just a PoC/MVC/Experiment; we'll tidy up the design once we have feedback.

Iterative development is a beautiful thing and a cornerstone of modern software processes. The problem is applying the same approach to an API design. Unlike code, an interface is a promise between one and many individuals. And no matter how an API producer might imply that the relationship has no strings attached, breaking promises undermines trust and hurts feelings.

It is tough to get otherwise busy developers to spend their precious time creating code for an interface the first time. Imagine their excitement discovering their work was invalidated and that they could now re-implement what was previously working? Long story short, most don't.

7. It's internal and on-prem, so we don't need to worry about Auth for a V1.

I get it; developers are under a deadline and looking for some way to jettison features later. However, relying on implicit trust, or clients doing the right thing because "they're one of us", is a no-no. In light of increasing security breaches, more companies are moving to a zero trust cybersecurity approach, continuously validating at every stage of the digital interaction.

Implicit trust means that users – including malicious actors – can move laterally to access or exfiltrate sensitive data once inside. Even if your API wasn't how that threat got into the building, you do not want to be how they downloaded the payroll records.

With an increasingly remote and distributed workforce, continued migration to other people's servers (the cloud) taking a zero-trust approach has never been more critical.

6. Caching does not belong in an HTTP API.

As stated by RESTfulAPI.net:

"Caching is the ability to store copies of frequently accessed data in several places along the request-response path."

Leveraging caches improve the API experience by:

• Reducing bandwidth
• Reducing latency
• Reducing server load
• Bridging network failures

To ignore caching's usefulness to an API is like eschewing indoor plumbing; sure, you can make things work, but at what cost?

5. I found this software tool that generates OAS3 automatically!" (Joe Malin)

Harold "Hal" Abelson is a Massachusetts Institute of Technology (MIT) professor, a fellow of the Institute of Electrical and Electronics Engineers (IEEE), and a founding director of both Creative Commons and the Free Software Foundation. In other words, he knows he stuff. When it came to the communicative power of software artifacts, he had this to say:

"Programs must be written for people to read, and only incidentally for machines to execute."

Auto-generating an OpenAPI description from an existing API, whether by code or traffic introspection, is a fine place to start. But no generalized algorithm will create a nuanced, detailed reference designed for a specific audience context. Endless, ongoing support happens when people mistake the starting line for the end destination.

4. We'll future proof the design by returning everything we have, and the consumer can sort it out.

Designing an API requires making decisions. Many of these decisions are made with imperfect knowledge in the time available. A common set of compromises lies around which information is necessary to fulfill the desired use case.

Getting one of these decisions wrong can, in some cases, require a version bump as the design team incorporates new learnings. Done well, the API can grow and evolve with its intended audience.

Sometimes, however, teams attempt to defer critical decision-making. By doing so, they instead pass on the cognitive load to the client. Returning everything doesn't bypass the evolution certainty, either. It just demonstrates contempt for the integrator's time. If an API user wants the digital equivalent of a cake, then give them a cake. Don't foist the raw ingredients upon them with documentation wishing them the best of luck.

3. We're done when the API is in production.

Your clients' mental model of a problem space may be different from the one your team shipped to production. Further, the behaviors demonstrated in the real world may differ from what you were told when discussing idealized hypotheticals.

It is like this: I might tell you, in a casual conversation, that I'm eating healthier. However, at 7 pm and under pressure to put dinner on the table, there I am, ordering pizza. The same applies to what behaviors clients aspire to versus what they actually implement.

Getting working software into a production environment is a significant milestone for any product. However, when it comes to APIs, that is where the real lessons begin.

2. If you use GraphQL, you don't need to design an API.

A different set of design decisions should not be conflated with no design required. Whether it is calculating allowed query complexity, determining appropriate namespaces, or putting in the effort to create version-less schemas, a "good" GraphQL design still necessitates several design decisions.

1. We'll Update the Docs Later.

Documentation debt is a form of technical debt. It is a lie told for momentary expediency. Over time, any initial gains will be dwarfed by the time, effort, and maintenance costs required for ongoing support - costs that, ironically, detract from addressing the documentation omissions. Furthermore, the longer the documentation is left unaddressed, the more effort will be required to repair the damage done.