How to Design A Good API and Why It Matters

Why is API Design Important?

APIs can be among a company's greatest assets
- Customers invest heavily: buying, writing, learning
- Cost to stop using an API can be prohibitive
- Successful public APIs capture customers
Can also be among company's greatest liability
- Bad API can cause unending stream of support calls
- Can inhibit ability to move forward
public APIs are forever - one chance to get it right

Why is API Design Important to You?

If you program, you are API designer
- Good code is modular - each module has an API
Useful modules tend to get reused
- Once module has users, can't change API at will
- Good reusable modules are corporate assets
Thinking in terms of APIs improve code quality

Characteristics of a Good API

Easy to learn
Easy to use, even without documentation
Hard to misue
Easy to read and maintain code that uses it
Sufficiently powerful to satisfy requirement
Easy to evolve
Appropriate to audience

Outline

The Process of API Design 2 General Principles
Class Design
Method Design
Exception Design
Refactoring API Designs

The process of API Design

Gather requirement - with a healthy degree of skepticism

Start with Short Spec - 1 page is ideal

Write to your API early and often

Maintain realistic expectation.