Seattle API Meeting Notes

gistfile1.txt

Seattle API Meeting Notes

John Musser @johnmusser / API Science @apiscience

10 Reasons Developers Hate Your API

Documentation:
  Good Examples:
    https://www.twilio.com/docs
    https://stripe.com/docs/api
  Live Documentation
    https://github.com/wordnik/swagger-core
    iodocs from mashery
    raml.org
    api blueprint apiary.io?
Poor Communication
  Fixes: 
    Have a changelog - apichangelog.com
    Have a roadmap - https://developers.facebook.com/roadmap
    Release Notes
    API Blog - http://aws.typepad.com/
    Forum - http://stackoverflow.com/questions/tagged/soundcloud
    Email to developers (newsletter)
Don't Make It Easy
  Fixes
    https://www.twilio.com/voice/api
    Fast Signup - https://manage.stripe.com/register
    1-2-3, getting started guide ex. developer.constantcontact.com/get-started.html
    Quickstart guides
    Free & Trial plans of your product so they can try the api
    Add lots of SDK's for multiple languages
    Use github.com - sample apps
Lawyers
  Fixes
    Be clear ex. 500px.com/terms
    Set the tone - ex. https://www.etsy.com/developers/terms-of-use
    Shorter = better - http://googledevelopers.blogspot.com
    Think long term - deprecation policy - developers.google.com/youtube/terms
    Share the wealth - http://slideshare.net/jmusser
Your API is unreliable
  Fixes
    API Status Page status.aws.amazon.com
    Monitor your api
    Don't hide behind your outages - blog.akismet.com
You don't give me the tools to succeed
  Fixes
    Dev Dashboard - ex. https://manage.stripe.com/test/dashboard
    Debug log on the server - twilio has this
    Test Sandbox
    Playground
    Test console - apigee.com/providers
You're marketing to me not helping me
  Fixes
    Evangelists - http://sendgrid.com/developers
    Events - https://www.twilio.com/conference
    Hackathons
Your api is too complex
  Fixes
    Use REST
    Use JSON - xml is dying as json is rising
    Be pragmatic  book - web api design brian mulloy
Time to hello world is too long
  Fixes
    Great DX - developerexperience.org
You haven't learned (from the best)
  Fixes
    Use role models - twilio, stripe, github, sendgrid
    Keep learning - conferences and meetups on apis
    
API is never done...