12 API Design Mistakes Senior Engineers Notice Immediately

The API Design Mistakes Experienced Engineers Never Make, Broken Down With the Junior Version and the Senior Fix

An API is a contract.

It defines how different pieces of software communicate, and once it is published, other systems and teams depend on it.

This makes API design one of the highest-leverage skills in engineering, because a well-designed API is easy to use, hard to misuse, and able to evolve without breaking the people who depend on it, while a poorly designed one causes friction and breakage for years.

API design also quietly reveals an engineer’s experience.

Two engineers can each build an API that technically works, that returns the right data and handles the basic cases.

Yet the design choices they make, the structure of the endpoints, the handling of errors, the approach to evolution and scale, expose how much they understand about building software that others rely on.

Reviewers, interviewers, and teammates read these signals immediately, often without consciously naming them.

The mistakes that make an engineer look junior are rarely dramatic. They are not crashes or obvious bugs. They are subtle design decisions that work in the moment but reveal a lack of awareness about consumers, scale, evolution, and failure.

An experienced engineer notices them instantly, because each one creates problems that they have already learned to avoid.

This article covers twelve of the most common and telling API design mistakes. For each one, it shows the junior version, explains why it is a problem and what it signals, and lays out what senior engineers do instead.

The goal is not to memorize rules but to understand the thinking behind good API design, so that the senior choices become natural.

A Quick Word on What These Mistakes Have in Common

Before the list, it helps to see the pattern that connects these mistakes.

Almost every one comes from designing an API for the moment rather than for its consumers and its future.

A junior engineer tends to build the API that satisfies the immediate task, mirroring whatever is convenient internally.

A senior engineer designs the API as a durable contract, thinking about the clients who will use it, the scale it must handle, the failures it must survive, and the changes it must accommodate over time.