api-design

Overview

Based on "A Philosophy of Software Design" by John Ousterhout. Ousterhout's key principle: modules should be deep - simple interface, powerful implementation. Applied to APIs: the surface area exposed to callers should be as small as possible, while the behavior provided should be as rich as possible. A leaky abstraction (where callers need to understand implementation details) is a design failure.

Workflow

Step 1: Define the API's job

Before designing any endpoint, state what the API enables:

• What is the caller trying to accomplish?
• What information does the caller have?
• What should the API hide from the caller?

Ousterhout: if callers need to know how the API works internally to use it correctly, the API is leaky.