This document discusses applying design principles to APIs. It is divided into four parts. Part I focuses on empathizing with developers by following best practices throughout the development cycle, handling errors transparently, and keeping the API status and methods clearly visible. The document provides checkslists of specific things API providers can do at each stage to be helpful, harmless, and honest from the developer perspective. Parts II through IV will cover additional design principles for APIs.

1. Applying Design Principles
to APIs
In Four Parts
Brian Mulloy
@landlessness
Apigee
@apigee

2. “Whatever is worth doing at all, is worth
doing well.”
-Philip Dormer Stanhope
Earl of Chesterfield
1746

3. amazon.com

4. Baker’s Dozen
1. Development Cycle
2. Errors
3. Visibility
4. Flexibility-Usability Tradeoff
5. Hick’s Law
6. 80/20 Rule
7. Inverted Pyramid
8. Advance Organizer
9. Consistency
10. Self Similarity
11. Aesthetic-Usability Effect
12. Cost-Benefit
13. Immersion

5. Four Parts
I. Empathize
Development Cycle ● Errors ● Visibility
II. Don’t Overwhelm
Flexibility-Usability Tradeoff ● Hick’s Law ● 80/20 Rule ● Inverted Pyramid
III. Don’t Reinvent the Wheel
Advance Organizer ● Consistency ● Self Similarity
IV. Be Beautiful
Aesthetic-Usability Effect ● Cost-Benefit ● Immersion

6. Part I: Empathize
i. Development Cycle
ii. Errors
iii. Visibility

7. “ Successful products typically follow four stages
of creation: requirements, design,
development, and testing.
Development Cycle
Universal Principles of Design

8. Questions to ask at each phase:
1. What is the developer doing?
2. How can we help?

9. Development Cycle: Requirements

10. Share our domain knowledge

15. Share our domain knowledge
✓ Educate others about our domain
✓ Certify our partner developers

16. Development Cycle: Design

17. Point the way

21. Point the way
✓ Inspire with an app gallery
✓ Guide the design of apps
✓ List the objects in our system

22. Development Cycle: Development

23. Share our API knowledge

27. Share our API knowledge
✓ Engage developers with an API console
✓ Be accessible via forums, social media & email

28. Development Cycle: Testing

29. Ask for input, give data

33. Ask for input, give data
✓ Receive bugs & feature requests directly from developers
✓ Show each developer his API data

34. Development Cycle
Universal Principles of Design
✓ Educate others about our domain
✓ Certify our partner developers
✓ Inspire with an app gallery
✓ Guide the design of apps
✓ List the objects in our system
✓ Engage developers with an API console
✓ Be accessible via forums, social media & email
✓ Receive bugs & feature requests directly from developers
✓ Show each developer his API data

35. “ An action or omission of action yielding an
unintended consequence.
Errors
Universal Principles of Design

36. Make it easy to learn from mistakes

40. Make it easy to learn from mistakes
✓ Respond with HTTP status codes for apps
✓ Respond with verbose messages for app developers
✓ Create social error pages with details and hints

41. “ The usability of a system is improved when its
status and methods of use are clearly visible.
Visibility
Universal Principles of Design

42. Be transparent and human

46. Be transparent and human
✓ Broadcast system status and alerts
✓ Apologize for mistakes and give details
✓ Publish the API product roadmap

47. End of Part I: Empathize
i. Development Cycle
ii. Errors
iii. Visibility

48. Part 1: Checklist
✓ Educate others about our domain
✓ Certify our partner developers
✓ Inspire with an app gallery
✓ Guide the design of apps
✓ List the objects in our system
✓ Engage developers with an API console
✓ Be accessible via forums, social media & email
✓ Receive bugs & feature requests directly from developers
✓ Show each developer his API data
✓ Respond with HTTP status codes for apps
✓ Respond with verbose messages for app developers
✓ Create social error pages with details and hints
✓ Broadcast system status and alerts
✓ Apologize for mistakes and give details
✓ Publish the API product roadmap

49. Four Parts
I. Empathize
Development Cycle ● Errors ● Visibility
II. Don’t Overwhelm
Flexibility-Usability Tradeoff ● Hick’s Law ● 80/20 Rule ● Inverted Pyramid
III. Don’t Reinvent the Wheel
Advance Organizer ● Consistency ● Self Similarity
IV. Be Beautiful
Aesthetic-Usability Effect ● Cost-Benefit ● Immersion

50. THANK YOU
Questions and ideas to:
Brian Mulloy
@landlessness
brian@apigee.com