API Design Guidelines - Progressive APIs

What are progressive APIs ?

1. Low barrier to entry (and get progressively difficult)
2. Powerful
3. Consistent

API Design Principles

1. Scenario-Driven Design
a. Define top scenarios.
b. Write code samples, design API later.
c. Make top scenarios easy, make the rest possible.
d. Usability test top scenarios. (Preferably other language)

2. Support Experimentation
a. Obvious entry points
A good way to indicate entry point is to use domain correspondence.
b. Minimal initialization, sensible defaults
c. Usage of properties
d. Immediate feedback (exception)

3. Aggregate Component
a. Create, set and call usage pattern
b. They build on the factored types

4. Self-Documenting APIs
a. Consistency
If you learn one part, you can know the other part
b. Progressive documentation
It has to start with simple scenario and then go to advanced concepts.


5. Keep things simple
a. Number of objects - less objects should be required to setup.
b. OO design methodologies is not meant for API design.

API Design Guidelines - Designing Inheritance Hierarchies

1. Prefer broad, shallow hierarchies
a. Less than or equal to two additional levels = rough rule !
b. Contracts and responsibilities are difficult to maintain and explain in deep hierarchies

2. Consider making base classes not constructible (use abstract class)
a. Make it clear what the class is for
b. Provide a protected constructor for subclasses to call

3. By default, everything should be non-virtual.
a. There is the danger and power of virtual methods
i. Danger : Owner of base classes cannot control what subclasses do
ii. Power : Base class don't have to change as new subclasses are created
b. Always consider LSP

4. Use abstract members only where it is absolutely required
a. There is more chance of introducing bugs.

5. Interface vs. Base Classes
a. Its easy to add members to base classes but not to interface. You have to create a new interface version.