Overview
• Why are APIs different?
• Why are APIs bad?
• How to fix that?
* APIs = REST/HTTP APIs
Jakub Nesetril
• backend dev (~8 years)
• frontend dev (~5 years)
• founder of Apiary
Apiary
• API Design, Documentation & Testing Tools
• 10,000s APIs, developers, companies, ideas
• Largest API community worldwide
What is an API?
API is UI to DataUser Experience
Design
Subjective
Simplicity
Conversion RatesEmotions
ProductivityUsability Studies
Culturally Dependent
Hackathons
Great! Make good design, right?
Empathy is HARD!
Provider Consumer
Uptime
Caching
Security
Maintenance
Versioning
ValidationCan It Be Done?
Debugging
Support
TTFHW
Example
Latency
Java
Rails
Scala
Erlang
jQuery
ObjC
AngularJS
So what?
Traditional API Development
Design
Implementation
Customer
3-6 weeks
3-6 months
Problem: API providers don't understand API consumers
(and vice versa)
Want good APIs? !
Empower the Frontend
Let's turn that on it's head
Design
Implementation
Customer
Frontend developer co-designs an API
Backend developers get implementation specs
(in form of tests)
API Blueprint
• human-readable & human-writable
• based on Markdown, you already know it
• structured reasoning about APIs
# 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
demo
API Lifecycle
Design
Prototype
Implementation
Delivery
Feedback
What happens when you're offline?
git workflow demo
Frontend
Backend
Contract
Concurrent Development
mocks
tests
Apiary for Teams
• roles
• integration with GitHub
• custom docs visuals
• teams up to 20 users
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”
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”
Source Code
Format: https://github.com/apiaryio/api-blueprint
Testing: https://github.com/apiaryio/dredd
JS SDK: https://github.com/apiaryio/apiblueprint-sdk
@apiaryio http://apiary.io/
!
@jakubnesetril
Thank You Questions?
Top Related