Lesson 10: API Design: Creating Interfaces That Feel Good to Use
An API (Application Programming Interface) is the public face of your code, whether it’s an HTTP endpoint or a public method within a class. The quality of this interface determines the Vibe experienced by its consumers.
Principle 1: Predictable and Intuitive Endpoints (External API)
External APIs (like REST endpoints) should adhere to standard conventions to minimize cognitive load for external users.
- Use Nouns, Not Verbs, for Resources:
/usersnot/getUsers. - Use HTTP Verbs for Actions: GET (retrieve), POST (create), PUT/PATCH (update), DELETE (remove).
- Consistent Response Structure: Always return predictable data, status codes, and error formats (e.g., JSON response with consistent error keys).
Principle 2: Minimalist Internal Interfaces (DX Vibe)
When designing a class or module interface, strive for simplicity. Consumers should not need to know the complex internal workings to use it.
The Law of Demeter (The 'Don't Talk to Strangers' Vibe)
Avoid method chaining that requires navigating deep object structures, as this tightly couples your code.
python
Bad Vibe: Tight coupling, long chain
user.getAccount().getSubscription().getPlan().name
Good Vibe: The User object abstracts the complexity
user.getSubscriptionPlanName()
Principle 3: Defaults and Sensible Constraints
Design your APIs to accept the most common use case with minimal effort, providing sensible default values. If a parameter is almost always 'true', make 'true' the default.