API design

Neil Ernst

2025-10-27

In-Class Exercise: Designing a `MeetingTime` API

Objective: To practice applying key API design principles (clarity, usability, preventing misuse) by designing a simple, robust API.

Scenario: You are on a team building a new calendar application. Your task is to design the primary class used to represent a time slot for a meeting. The system needs to handle scheduling, detect overlaps, and calculate durations.

Your Task (15-20 minutes):

In small groups, design a MeetingTime class (or struct/interface). Don’t write the implementation; focus only on the public-facing API: class name, constructor(s), public methods, and properties.

A senior developer has provided a first-pass “bad” API to get you started. Critique this API first, then design a better one.

Initial (Flawed) API Proposal:

// Represents a time slot for a meeting
public class MeetingTime {
  // Constructor uses 24-hour time, e.g., 13, 30 -> 1:30 PM
  public MeetingTime(int startHour, int startMinute, int endHour, int endMinute);
  // Returns the duration of the meeting
  public int getDuration();
  // Is this meeting at the same time as another?
  public boolean conflicts(MeetingTime other);
}

Part 1: Critique (5 minutes)

Discuss with your group and identify at least three specific flaws with the MeetingTime API above, based on Joshua Bloch’s principles. Think about:

Is it easy to use correctly?
Is it hard to use incorrectly?
Are the names clear?
Does it force the client to do extra work?

Part 2: Redesign (10 minutes)

Design a new, improved API for representing a meeting time. As you design, consider the following questions inspired by Bloch’s lecture:

How can you make it impossible to create an invalid MeetingTime? (e.g., a meeting that ends before it starts, or has an hour of 25).
What are the essential pieces of data? Can you represent the time slot with fewer, or different, parameters? (e.g., start time and duration vs. start time and end time). What are the trade-offs?

What units should your methods return? Is getDuration() clear enough? What does the int represent?
Is the name conflicts the best choice? What about overlapsWith? Is there a difference?
Should the class be mutable or immutable? What are the pros and cons of allowing a MeetingTime to be changed after it’s created?