Designing the API First

Design from the caller's perspective

The single most useful trick is to write the client code you wish you could call first, before any implementation exists. Pretend the class is already done and write the few lines that use it: const ticket = lot.park(car);. Does that read cleanly? Is it obvious what comes back, and what happens when the lot is full? You're designing the API by consuming it, which is the only perspective that matters — an API is judged by the people who call it, not by the person who wrote it. This is the heart of API-first (sometimes called consumer-driven or outside-in) design.

What a good signature communicates

A method signature is a tiny contract that should answer four questions at a glance: what does it do (the name), what does it need (the parameters), what does it give back (the return type), and how can it fail (the error style). A signature like boolean doIt(int a, int b, boolean flag) answers none of them — you have to read the body to learn anything. Result<Ticket> park(Vehicle vehicle) answers all four: it parks a vehicle, it needs a vehicle, it returns a ticket, and the Result wrapper says it can fail in a way you must handle. Good signatures are intention-revealing: the name and types tell the story so the body doesn't have to.

The decisions you surface early

Designing the API first forces a handful of decisions into the open before they harden into accidents:

• Return type — void (the caller learns nothing), a raw Ticket (fine on the happy path, but what about failure?), or a Result<Ticket> / Optional<Ticket> that makes "might not produce one" explicit in the type.
• Error-handling style — throw an exception, return null, return a Result / Optional, or return an error code. Pick one deliberately and be consistent; mixing them is what makes a surface miserable to call.
• Naming — vague verbs like process(), handle(), doIt() hide intent; park(vehicle), cancelBooking(id), reserveSeat(...) reveal it.
• Parameter shape — a long positional list (park(plate, color, height, isElectric, level)) is easy to mis-order; a single parameter object (park(ParkRequest)) is self-documenting and grows without breaking callers.
• Command–query separation — a method should either do something (a command, often void or returning a receipt) or answer something (a query, with no side effects), not quietly both.
• Idempotency — can the caller safely retry park after a timeout without double-parking? Designing the contract is where you decide and document that.
• Minimal surface — expose the fewest public members that let callers do their job; every extra public method is a promise you must keep forever.

Keep the surface minimal — hide the internals

The public API is a promise: once a caller depends on a method, you can't change it freely without breaking them. So the contract should expose intent and hide mechanism — this is encapsulation and abstraction in action. A clean park(vehicle) says nothing about how spots are tracked, whether there's a database, or what an int spotIndex means internally. The moment a signature leaks HashMap<String,Integer> spots or a Connection conn parameter, the caller is coupled to your implementation, and you've lost the freedom to change it. A deep module — a small interface over a lot of hidden functionality — is the goal; a shallow one that exposes its guts is a liability.

Contracts let implementations be swapped (DIP)

When the API is an interface rather than a concrete class, you gain the ability to swap what's behind it. interface ParkingLot { park(v): Result<Ticket>; } can be backed by an in-memory lot today and a distributed one tomorrow, and no caller changes. High-level code depends on the abstraction, not the concrete type — that's the Dependency Inversion Principle. Designing the API first naturally produces these thin contracts, because you're describing what the caller needs, not how you'll provide it.

Why agreeing first unblocks everyone

Once the contract is agreed, work parallelizes. One engineer builds the real implementation behind the interface; another builds the caller against a mock of that same interface; a third writes tests that assert the contract's behavior. None of them wait on each other, because the interface is the shared truth. Testing gets easier for the same reason: you mock against the interface, verify the caller handles every documented outcome (including the failure cases the Result type forces it to acknowledge), and you're done. A contract designed first is a coordination point; an API that fell out of the implementation is a surprise everyone discovers late.

Leaky vs. clean: a contrast

Here's the same operation as a leaky contract and a clean one. The leaky version returns a bare boolean, smuggles results out through an out-parameter, takes an error-prone positional list, and exposes an internal index. The clean version is an intention-revealing interface returning an explicit result type over a parameter object:

// ❌ LEAKY — boolean return, out-param, positional soup, exposed internals
class Lot {
  // did it work? caller can't tell why it failed.
  park(plate: string, color: string, h: number, ev: boolean,
       outSpotIndex: { value: number }): boolean { /* ... */ }
}
const out = { value: -1 };
if (!lot.park("AB-12", "red", 1.6, false, out)) { /* why?? */ }
// caller must know what 'outSpotIndex' means — that's an internal detail

// ✅ CLEAN — intention-revealing interface, result type, parameter object
interface ParkingLot {
  park(vehicle: Vehicle): Result<Ticket>;   // one obvious thing; failure is in the type
}
const r = lot.park(car);
if (r.ok) issue(r.value);           // r.value is a Ticket — a domain object
else      show(r.error.message);    // the caller MUST handle the failure case

When designing the API first pays off most

Reach for API-first design whenever a contract will be shared or outlive its first caller: a public library or SDK, a service consumed by another team, a module sitting at a subsystem boundary, or anything you'll mock heavily in tests. The cost of a bad signature scales with the number of callers depending on it — a published interface is expensive to change because you can't fix every caller in one commit. Spend the design effort up front exactly where the API will be hard to change later.