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.

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