Avoiding API Waterfalls
32
founder & CEO of Apiary Jakub Nesetril AVOIDING WATERFALLS Tuesday, December 4, 12
-
Upload
jakub-nesetril -
Category
Technology
-
view
2.972 -
download
1
Transcript of Avoiding API Waterfalls
founder & CEO of ApiaryJakub Nesetril
AVOIDING WATERFALLS
Tuesday, December 4, 12
GitHub for APIsapiary.io
Tuesday, December 4, 12
WHY WE DO THINGS
• documentation and tooling, not architecture
• man-years of API infrastructure work
• companies & teams re-inventing the wheel
Tuesday, December 4, 12
3 PROBLEMS
Tuesday, December 4, 12
API DESIGN
Tuesday, December 4, 12
WE START WITH WHITEBOARD
Tuesday, December 4, 12
THEN CODE THE DESIGN
Tuesday, December 4, 12
OFFER IT TO CUSTOMERS
Tuesday, December 4, 12
AND ALL FAILS, BADLY
Tuesday, December 4, 12
WHERE DID WE GO WRONG?
Tuesday, December 4, 12
WATERFALL PROCESS
Tuesday, December 4, 12
API DESIGNREIMAGINED
HOW CAN WE GO AGILE?
Tuesday, December 4, 12
MAKE A DESIGN FIRST
Tuesday, December 4, 12
HOST: http://api.twitter.com/ --- Twitter API 3.0 ------Welcome to our API. Comments support Markdown syntax---
-- Retrieve Tweets --GET /tweets> Accept: application/json< 200< Content-Type: application/json{ "items": [ { "url": "/feed", "range":"2ZY48XPZ", "quantity": 1, "name": "New socks", "price": 1.25 }] }
BUT WRITE IT DOWN FOR ALL TO USE
Tuesday, December 4, 12
OFFER A MOCK SERVER
Tuesday, December 4, 12
INVOLVE THE CUSTOMER
Tuesday, December 4, 12
CODE WITH SPEC TESTS
Tuesday, December 4, 12
apiary.io
Mock > Use > Implement
Tuesday, December 4, 12
DOCUMENTATION
Tuesday, December 4, 12
#2: DOCUMENTATION
• how do I make an HTTP call?
• try to follow documentation but API behaves differently
• is it invalid? is it outdated? am I doing it wrong?
Tuesday, December 4, 12
DOCUMENTATIONREIMAGINED
Tuesday, December 4, 12
DOCUMENTATION
• includes runnable code examples (NOT API console)
• is backed up by automated tests (never out of date)
Tuesday, December 4, 12
Tuesday, December 4, 12
SUPPORT
Tuesday, December 4, 12
#3: SUPPORT
• my API calls are failing, no idea why
• contacting customer support (that caters to shoe customers)
• bumping my head against first-tier support for days until I get connected to developers
• by that time, debug information is lost, logs are rotated, new product version is deployed…
Tuesday, December 4, 12
SUPPORTREIMAGINED
Tuesday, December 4, 12
SUPPORT
• includes self-service debugger
• API support requests routed directly to devs with debugging information included
Tuesday, December 4, 12
Tuesday, December 4, 12
apiary.io
Mock > Use > Implement
DocumentationAutomatedTesting
Tuesday, December 4, 12
http://github.com/apiaryiohttp://support.apiary.io/
COME HELP US
Tuesday, December 4, 12
PHOTO CREDITS
http://www.flickr.com/photos/ironrodart/4308675209/sizes/o/http://www.flickr.com/photos/schlosi/6153707178/sizes/l/http://www.flickr.com/photos/72153088@N08/6510934443/sizes/l/http://www.flickr.com/photos/psd/3470234703/sizes/l/http://www.flickr.com/photos/code_martial/2501920341/sizes/l/http://www.flickr.com/photos/weesen/3589267112/sizes/l/http://www.flickr.com/photos/weesen/3588454913/sizes/l/http://www.flickr.com/photos/weesen/3589258380/sizes/l/http://www.flickr.com/photos/polishsausagequeen/2178265710/http://www.flickr.com/photos/stupidmommy/2649444581/sizes/z/
Tuesday, December 4, 12
