The document discusses key principles for designing APIs, including that an API serves as an interface between systems and cultures. It emphasizes involving customers early in the design process, starting with a wireframe, and maintaining exhaustive and up-to-date documentation that is automatically generated and tested. The document concludes that APIs should have their contract separated from implementation and encourages automating the design process.

1. Harmony in API Design
jakub@apiary.io

2. What is an API?

5. API is UI to Data

6. API is UI to Data

7. API is UI to Data
User Experience

8. API is UI to Data
Design
User Experience

9. API is UI to Data
Emotions
Design
User Experience

10. API is UI to Data
Emotions
Design
User Experience
Subjective

11. API is UI to Data
Emotions
Design
User Experience
Subjective
Culturally Dependent

12. API is UI to Data
Emotions
Simplicity
Design
User Experience
Subjective
Culturally Dependent

13. API is UI to Data
Emotions
Simplicity
Design
Productivity
User Experience
Subjective
Culturally Dependent

14. API is UI to Data
Emotions
Conversion Rates
Simplicity
Design
Productivity
User Experience
Subjective
Culturally Dependent

15. API is UI to Data
Emotions
Conversion Rates
Simplicity
Design
Productivity
User Experience
Usability Studies
Subjective
Culturally Dependent

16. API is UI to Data
Emotions
Conversion Rates
Simplicity
Design
Productivity
User Experience
Hackathons
Subjective
Culturally Dependent

17. Nobody thinks THEIR design sucks

20. Provider
Consumer

21. Java
Provider
Rails
Scala
Erlang
Consumer

22. Java
jQuery
Provider
Consumer
Rails
ObjC
PHP
Scala
Erlang

23. Validation
Uptime
Java
Maintenance
Provider
Caching Rails
Scala
Security
jQuery
Consumer
ObjC
Versioning
Erlang
PHP

24. Latency
Validation
Uptime
Java
Maintenance
Provider
Caching Rails
Scala
Security
Versioning
Erlang
Can It Be Done?
TTFHW
jQuery
Consumer
Debugging
ObjC
PHP
Example
Support

25. So?

26. 1. Start With a Wireframe
• a design intent
• usually an API description language
• at Apiary we use API Blueprint

27. 2. Involve Your Customers
• find your early-adopters before you code
• create an API mock that they can use
• fork/pull-request

28. 3. Have Great Documentation
• generated automatically
• must be exhaustive and up-to-date
• your code is automatically tested; so
must your documentation

29. 4. Separate Contract from
Implementation

30. Summary
• API is UI for Data & Interface between cultures
• Involve your customers early
• Automate

31. Thank You
@apiaryio
http://apiary.io/
!
@jakubnesetril