Talks - Lynn Root: The Design of Everyday APIs

APIs should be designed with discoverability, affordances, signifiers, constraints, mappings, and feedback to create an intuitive user experience

Follow language idioms and conventions - leverage what the programming language naturally affords and what users already know

Make APIs flexible for users while maintaining clear constraints - allow basic use cases to work easily while supporting more advanced functionality

Minimize cognitive load by:

• Using consistent and appropriate method naming
• Limiting positional arguments in favor of keyword arguments
• Providing sensible defaults
• Not requiring users to provide data the API can generate itself

Use symmetrical naming patterns and logical pairs (create/delete, get/set) to make APIs predictable

Make error handling and feedback clear and unambiguous - communicate results effectively back to users

Design for composability - operations should return data types that can be chained together

Provide convenience methods to reduce boilerplate and repetitive code (like iteration helpers)

Put the most important information “above the fold” in documentation - how to install, basic examples, and getting started guide

Test the API by writing example user code first to identify pain points and unnecessary complexity early

Clean up method names by removing redundant nouns when the object type is clear from context