Evolving an API without breaking callers

The OCP habit in one API

Open for extension, closed for modification — the same idea as Open/Closed. You extend with an overload or an options object. You do not redefine park. At HTTP scale this is API compatibility and consumer contracts. In a machine-coding round you “break” only the code on the whiteboard, but saying “existing callers keep working” is the habit interviewers want.

Java: defaults then options

class ParkingLot {
  Ticket park(Vehicle vehicle) {
    return park(vehicle, ParkOptions.defaults());
  }

  Ticket park(Vehicle vehicle, ParkOptions options) {
    SpotSpec spec = options.needsCharger() ? SpotSpec.CHARGER : SpotSpec.ANY;
    return allocation.choose(freeSpots(), vehicle, spec)
        .map(spot -> openTicket(vehicle, spot))
        .orElseThrow(SpotUnavailable::new);
  }
}

final class ParkOptions {
  private final boolean needsCharger;
  private final boolean valet;

  static ParkOptions defaults() {
    return new ParkOptions(false, false);
  }

  ParkOptions(boolean needsCharger, boolean valet) {
    this.needsCharger = needsCharger;
    this.valet = valet;
  }

  boolean needsCharger() { return needsCharger; }
  boolean valet() { return valet; }
}

When you must rename

A breaking change that changes meaning should be a rename. pay() that used to take cash and now also talks to a card network should become pay(PaymentMethod), not a boolean old callers pass wrong. If park used to mean “now” and you add “hold for two hours,” that is reserve — a new use case, not a flag on park.

Java: a new verb, not a lying old one

class ParkingLot {
  Ticket park(Vehicle vehicle) { /* now, normal spot */ }

  Reservation reserve(Vehicle vehicle, TimeWindow window) {
    // hold a spot; do not call this park
    return reservations.hold(vehicle, window, clock.instant());
  }
}

Return types are part of the contract

park returning Ticket is a promise: callers will call ticket.id() without a null check. Switching to Optional<Ticket> is a compile break — honest, and you can discuss it. Switching to null on full is a runtime break — dishonest. Switching find from Optional to a throwing Ticket is also a break for callers who treated empty as “not found” rather than “crash.” Pick Optional for lookups and named exceptions for commands, then keep that pairing when the lot grows EV spots and valet.

Adding a method on Ticket (spotFloor()) is usually compatible: old callers ignore it. Changing Ticket from a class to a record that drops close() is not. The object API and the HTTP API share this rule: additive is easy; redefining meaning is a new version, which in LLD means a new name.

Java: ParkOptions that grows without a flag pile

final class ParkOptions {
  private final boolean needsCharger;
  private final boolean valet;
  private final Optional<ReservationId> reservation;

  static ParkOptions defaults() {
    return new ParkOptions(false, false, Optional.empty());
  }

  ParkOptions withCharger() {
    return new ParkOptions(true, valet, reservation);
  }

  ParkOptions withReservation(ReservationId id) {
    return new ParkOptions(needsCharger, valet, Optional.of(id));
  }
}