A quick overview of API Design Workflow, describing my views on waterfall API design approach, why we've built Apiary a certain way and random notes from the API industry

1. API Design Workflow
jakub@apiary.io

2. Overview
•Why are APIs different?
•Why are APIs bad?
•How to fix that?
* APIs = REST/HTTP APIs

3. Jakub Nesetril
• backend dev (~8 years)
• frontend dev (~5 years)
• founder of Apiary

4. Apiary
•API Design, Documentation & Testing Tools
•10,000s APIs, developers, companies, ideas
•Largest API community worldwide

5. What is an API?

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

8. Great!
Make good design, right?

9. Empathy is HARD!

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

12. So what?

13. Traditional API Development

17. Design
Implementation
Customer
3-6 weeks
3-6 months

18. Problem: API providers don't
understand API consumers
(and vice versa)

19. Want good APIs?
!
Empower the Frontend

20. Let's turn that on it's head

21. Design
Implementation
Customer

22. Frontend developer
co-designs an API

23. Backend developers get
implementation specs
(in form of tests)

24. API Blueprint
•human-readable & human-writable
•based on Markdown, you already know it
•structured reasoning about APIs

25. # Message of the Day API
A simple [MOTD](http://en.wikipedia.org/wiki/motd) API.
!
# Message [/messages/{id}]
This resource represents one particular message
identified by its *id*.
!
## Retrieve Message [GET]
Retrieve a message by its *id*.
!
+ Response 200 (text/plain)
!
Hello World!
!
## Delete Message [DELETE]
Delete a message.
**Warning:** This action **permanently** removes the
message from the database.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
API Blueprint

26. demo

28. API Lifecycle
Design
Prototype
Implementation
Feedback
Delivery

29. What happens when you're
offline?

30. git workflow demo

31. Concurrent Development
Frontend
Backend
Contract
mocks
tests

32. Apiary for Teams
• roles
• integration with GitHub
• custom docs visuals
• teams up to 20 users

33. Random Notes
•PMs aren’t technical, Dev’s aren’t
customer-focused
•The hardest thing about APIs is a push to
get things right the first time
•For larger teams, create a “style guide”

34. PMs aren’t technical, Dev’s
aren’t customer-focused

35. The hardest thing about APIs
is a push to get things right
the first time

36. For larger teams, create a
“style guide”

37. Source Code
Format: https://github.com/apiaryio/api-blueprint
Testing: https://github.com/apiaryio/dredd
JS SDK: https://github.com/apiaryio/apiblueprint-sdk

38. Thank You
Questions?
@apiaryio
http://apiary.io/
!
@jakubnesetril