12 Reasons Your API Sucks - Lone Star PHP

12 Reasons Your API Sucks - Lone Star PHP

New version: https://speakerdeck.com/caseysoftware/12-reasons-your-api-sucks-2017-rev

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. 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.

23365b2ae97212e561fb82442857d8bb?s=128

Keith Casey

April 25, 2014
Tweet

Transcript

  1. 12 REASONS YOUR API SUCKS KEITH CASEY HTTPS://JOIND.IN/10800 @CASEYSOFTWARE

  2. 12 STEPS TO SUCCESSFULLY LAUNCHING YOUR API KEITH CASEY HTTPS://JOIND.IN/10800

    @CASEYSOFTWARE
  3. None
  4. None
  5. Techstars London “Company to Watch” - Fintech 50 “Top five

    companies to watch from Hy!” - Engadget SXSW Accelerator 2014 Selected for the BBC Media Labs Currently in Private Beta
  6. http://TheAPIDesignBook.com

  7. WHAT IS DX? LOVE AT FIRST BYTE ADOPTION DAY TO

    DAY PUTTING IT ALL TOGETHER
  8. WHAT IS DX? LOVE AT FIRST BYTE ADOPTION DAY TO

    DAY PUTTING IT ALL TOGETHER
  9. Developer Experience is to Developers as User Experience is to

    Users* – That dude in front of you right now *sorta
  10. None
  11. “I set aside an hour..” Not really, but you really

    tried.. phone calls, emails, IM, etc, etc “do you have a minute?” TPS reports
  12. WHAT IS DX? LOVE AT FIRST BYTE ADOPTION DAY TO

    DAY PUTTING IT ALL TOGETHER
  13. 1. Documentation Ways to deliver documentation PDFs - [redacted] HTML

    - https://www.twilio.com/docs/api/rest
  14. 1. Documentation (cont) Let’s get interactive! Swagger - https://api-beta.op3nvoice.com/ docs

    iodocs - http://developer.rottentomatoes.com/ io-docs
  15. 2. Incomplete/Wrong Docs Helper documentation != API documentation

  16. 3. Getting started code

  17. 4. Too much boilerplate

  18. 5. SOAP as the interface Do I need to say

    more?
  19. 5. SOAP as the interface Well, probably

  20. 5. SOAP as the interface REST is like borrowing $10

    from a friend SOAP is like a mortgage
  21. WHAT IS DX? LOVE AT FIRST BYTE ADOPTION DAY TO

    DAY PUTTING IT ALL TOGETHER
  22. Who is the API for? Is this an internal API

    that was released publicly? Is this an API specifically built for external use? Where does the API fit into their business? aka Is it bolted on or a key part of the company?
  23. 6. Illogical/Inconsistencies Accounts Contacts ContactHistories Users ContactGroupings /api/v1/accounts /api/v1/contacts /api/v1/contact_histories

    ??? ???
  24. Sidebar: Remember, URIs just need to uniquely address resources, they

    don’t need to be human readable or pretty or even marginally cute.
  25. 6. Illogical/Inconsistencies Accounts Contacts ContactHistories Users ContactGroupings /api/v1/accounts /api/v1/contacts /api/v1/contact_histories

    ??? ???
  26. Accounts Contacts ContactHistories Users ContactGroupings /api/v1/accounts /api/v1/contacts /api/v1/contact_histories /api/v1/users ???

    6. Illogical/Inconsistencies
  27. Accounts Contacts ContactHistories Users ContactGroupings /api/v1/accounts /api/v1/contacts /api/v1/contact_histories /api/v1/users/current ???

    6. Illogical/Inconsistencies
  28. Accounts Contacts ContactHistories Users ContactGroupings /api/v1/accounts /api/v1/contacts /api/v1/contact_histories /api/v1/users/current /api/v1/contact_groupings

    6. Illogical/Inconsistencies
  29. Accounts Contacts ContactHistories Users ContactGroupings /api/v1/accounts /api/v1/contacts /api/v1/contact_histories /api/v1/users/current /api/v1/contact/:id/groupings

    6. Illogical/Inconsistencies
  30. 7. Poor workflow & modeling Affordances What is the API

    producer’s goal? What problem(s)/task(s) does it make simple? What do you want to do?
  31. 8. Numerous approaches

  32. POST -d (data) /api/v1/accounts /api/v1/contacts /api/v1/contact_histories /api/v1/users/current /api/v1/contact/:id/groupings ! 201,

    Location header 200, Resource 201, Location header 201, Location header 201, Location header 9. Payloads
  33. 10. Authentication Don’t roll your own methods

  34. WHAT IS DX? LOVE AT FIRST BYTE ADOPTION DAY TO

    DAY PUTTING IT ALL TOGETHER
  35. 11. Error Messages { “response_code”:”404”, “response_msg”:”There was an error.” }

  36. 11. Error Messages (cont) { “response_code”:”200”, “error_code”:”11007”, “response_msg”:”Item not found.”

    }
  37. 11. Error Messages (cont) { “response_code”:”404”, “error_code”:”11007”, “response_msg”:”Item not found.”

    }
  38. 12. Logging & Debugging

  39. Runscope

  40. WHAT IS DX? LOVE AT FIRST BYTE ADOPTION DAY TO

    DAY PUTTING IT ALL TOGETHER
  41. Beginning Documentation Consumable Accurate & complete Examples Simplicity in code

    & interfaces
  42. Adopting Logical & Consistent Designed workflows vs random junk The

    One True Way Consistent Payloads Authentication
  43. Supporting Error Messages & Handling Logging & Debugging

  44. 12 REASONS YOUR API SUCKS KEITH CASEY HTTPS://JOIND.IN/10800 @CASEYSOFTWARE

  45. 12 STEPS TO SUCCESSFULLY LAUNCHING YOUR API KEITH CASEY HTTPS://JOIND.IN/10800

    @CASEYSOFTWARE
  46. http://TheAPIDesignBook.com