12 Reasons your API Sucks (2017 Rev)

12 Reasons your API Sucks (2017 Rev)

(Revised for 2017)

Just like there are code smells through the rest of your project, there are API smells that make them hard to design, hard to launch, and hard to maintain. We’ll use this time to explore a few common APIs to highlight those issues and demonstrate strategies to fix the issues before they become problems.

Those first moments of using an API are pivotal. There’s nothing like downloading this week’s PDF of the documentation, setting up a SOAP client, reconfiguring all your URLs, and decoding the latest binary payloads. It makes your heart sing and your blood pressure rise.

23365b2ae97212e561fb82442857d8bb?s=128

Keith Casey

August 09, 2017
Tweet

Transcript

  1. 12 REASONS YOUR API SUCKS D. Keith Casey Jr keith@caseysoftware.com

    @CaseySoftware
  2. 12 STEPS TO SUCCESSFULLY LAUNCHING YOUR API D. Keith Casey

    Jr keith@caseysoftware.com @CaseySoftware
  3. WHO AM I? @CaseySoftware

  4. WHO AM I? @CaseySoftware

  5. WHO AM I? http://TheAPIDesignBook.com @CaseySoftware

  6. AGENDA • Assumptions • Developer Experience • Love at First

    Byte • Adoption • Day to Day @CaseySoftware
  7. AGENDA • Assumptions • Developer Experience • Love at First

    Byte • Adoption • Day to Day @CaseySoftware
  8. ASSUMPTIONS • APIs are an important part of your job

    • Use them on a regular basis • Potentially build them too • Sometimes public, sometimes private @CaseySoftware
  9. ASSUMPTIONS • Nothing is perfect • You make mistakes •

    Your providers make mistakes • That other team are knuckleheads @CaseySoftware
  10. AGENDA • Assumptions • Developer Experience • Love at First

    Byte • Adoption • Day to Day @CaseySoftware
  11. – D. Keith Casey, Jr. aka That guy in front

    of you, right now “Developers are users too”
  12. None
  13. “I SET ASIDE AN HOUR…” • Not really, but you

    really tried… • phone calls, emails, IM, Slack, etc, etc • “Do you have a minute?” • TPS reports
  14. AGENDA • Assumptions • Developer Experience • Love at First

    Byte • Adoption • Day to Day @CaseySoftware
  15. 1. DOCUMENTATION • Ways to deliver documentation • PDF -

    [redacted] • HTML - https://github.com/lord/slate
  16. 1. DOCUMENTATION (CONT) • Let’s get interactive! • Swagger -

    http://docs.clarify.io/api/ (Open API) • RAML, JSON Schema, API Blueprint
  17. 2. INCOMPLETE DOCS SDK docs != API docs

  18. SDK docs != API docs Good API docs = Reference

    Docs + Howtos 2. INCOMPLETE DOCS
  19. 3. GETTING STARTED CODE • Sample code that solves a

    problem
  20. 3. GETTING STARTED CODE • Sample code that solves an

    important problem
  21. 3. GETTING STARTED CODE • Sample code that solves an

    important problem MY
  22. 4. “INNOVATIVE” INTERFACES • You created your own… • HTTP

    verbs • Response codes • Or your own flippin’ protocols
  23. 5. AUTHENTICATION • Don’t roll your own “encryption” scheme •

    Don’t roll your own “new” methods
  24. • Don’t roll your own “encryption” scheme • Don’t roll

    your own “new” methods 5. AUTHENTICATION
  25. • Use an existing scheme like OAuth • Less (zero?)

    training required • Reuse common libraries for clients & server • Faster on boarding 5. AUTHENTICATION
  26. AGENDA • Assumptions • Developer Experience • Love at First

    Byte • Adoption • Day to Day @CaseySoftware
  27. 6. INCONSISTENCIES • Accounts • Contacts • ContactHistories • Users

    • ContactGroupings /api/v1/accounts /api/v1/contacts /api/v1/contact_histories ??? ??? @CaseySoftware
  28. • Accounts • Contacts • ContactHistories • Users • ContactGroupings

    /api/v1/accounts /api/v1/contacts /api/v1/contact_histories /api/v1/users /api/v1/contact_groupings 6. INCONSISTENCIES @CaseySoftware
  29. • Accounts • Contacts • ContactHistories • Users • ContactGroupings

    /api/v1/accounts /api/v1/contacts /api/v1/contact_histories /api/v1/users/current.json /api/v1/contact/:id/groupings 6. INCONSISTENCIES @CaseySoftware
  30. 201, Location header ??? 201, Location header 201, Location header

    201, Location header POST -d {data} /api/v1/accounts /api/v1/contacts /api/v1/contact_histories /api/v1/users/current.json /api/v1/contact/:id/groupings 6. INCONSISTENCIES @CaseySoftware
  31. 201, Location header 200, Resource 201, Location header 201, Location

    header 201, Location header POST -d {data} /api/v1/accounts /api/v1/contacts /api/v1/contact_histories /api/v1/users/current.json /api/v1/contact/:id/groupings 6. INCONSISTENCIES @CaseySoftware
  32. 7. POOR MODELING @CaseySoftware

  33. • Affordances • What problems/tasks does it makes simple? •

    What is the API producer’s goal? • What do you want to do? 7. POOR MODELING @CaseySoftware
  34. 8. STACK OVERFLOW PROBLEM @CaseySoftware

  35. AGENDA • Assumptions • Developer Experience • Love at First

    Byte • Adoption • Day to Day @CaseySoftware
  36. 9. YOUR SH.. STUFF IS BROKEN • Is Support run

    by developers? • What does your uptime look like? • Do you have a Trust page? @CaseySoftware
  37. 10. ERROR MESSAGES { “response_code”:“404”, “response_msg”:”There was an error.” }

    @CaseySoftware
  38. 10. ERROR MESSAGES { “response_code”:“404”, “response_msg”:”Item not found.” } @CaseySoftware

  39. 10. ERROR MESSAGES { “response_code”:“404”, “response_msg”:”Item not found.”, “error_code”:”E0000007” }

    @CaseySoftware
  40. 10. ERROR MESSAGES { “response_code”:“404”, “error_code”:”E0000007”, “response_msg”:”Item not found.”, “more_info”:”

    https://developer.okta.com/reference/error_codes/ #E0000007” } @CaseySoftware
  41. 11. LOGGING & DEBUGGING @CaseySoftware

  42. 11. LOGGING & DEBUGGING “Building your API Utility Belt” https://speakerdeck.com/caseysoftware/building-your-api-utility-belt

    @CaseySoftware
  43. RECAP • Assumptions • Developer Experience • Love at First

    Byte • Adoption • Day to Day @CaseySoftware
  44. STARTING • Documentation • Consumable • Accurate & Complete •

    Examples • Simplicity in Code & Interfaces @CaseySoftware
  45. BUILDING • Consistent aka “Principle of Least Surprise” • Designed

    Workflows • The One True Way • Authentication @CaseySoftware
  46. MAINTAINING • Error Messages & Handling • Logging & Debugging

    @CaseySoftware
  47. HEY JERK. THAT WAS ONLY 11. WHAT KIND OF GAME

    ARE YOU PLAYING HERE? @CaseySoftware
  48. OOPS. I LEFT ONE OUT.. @CaseySoftware

  49. DO YOU HAVE A BUSINESS MODEL? @CaseySoftware

  50. 12 REASONS YOUR API SUCKS D. Keith Casey Jr keith@caseysoftware.com

    @CaseySoftware
  51. WHO AM I? http://TheAPIDesignBook.com