Your API Sucks
Why developers hang up and how to stop that.
Marsh Gardiner @earth2marshProduct Manager, Apigee
• User experience wins• API users = developers• Developer experiences (generally) suck• But they don’t have to…
IN A NUTSHELLTHIS TALK
Simple things should be simple.
Complex things should be possible.
— Alan Kay
POST /InStock HTTP/1.1Host: www.example.orgContent-Type: application/soap+xml; charset=utf-8Content-Length: 299 <?xml version="1.0"?><soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Header> </soap:Header> <soap:Body> <m:GetStockPrice xmlns:m="http://www.example.org/stock"> <m:StockName>IBM</m:StockName> </m:GetStockPrice> </soap:Body></soap:Envelope>
http://api.twitter.com/1/statuses/public_timeline.json
Why REST is winning:
Why did youbuild an API?
Why is this so hard?
Why does Freemium work?
Do it better
Your API is a product.
Treat it that way.Your developers are your customers.
Your engineers may be great at writing the code behind your API.
Are they great at writing API docs?
“Because you can,” doesn’t mean, “you should.”
Good visual design involves restraint. Good code involves restraint. Good API design involves restraint.
Opacity is inscrutable. (Also, unforgivable.)
Give devs the information they need to succeed.
Put yourself in their shoes.
Recommended
