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.