12 Reasons Your API Sucks

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 D. KEITH CASEY JR. @CASEYSOFTWARE KEITH@CASEYSOFTWARE.COM
2. 12 STEPS TO SUCCESSFULLY LAUNCH YOUR API D. KEITH CASEY JR. @CASEYSOFTWARE KEITH@CASEYSOFTWARE.COM
3. Who am I?
4. Who am I?
5. Who am I? http://TheAPIDesignBook.com
6. AGENDA ASSUMPTIONS DEVELOPER EXPERIENCE LOVE AT FIRST BYTE ADOPTION DAY TO DAY
7. AGENDA ASSUMPTIONS DEVELOPER EXPERIENCE LOVE AT FIRST BYTE ADOPTION DAY TO DAY
8. Assumptions APIs are an important part of your job Use them on a regular basis Potentially build them too Sometimes public, sometimes private
9. Assumptions Nothing is perfect You make mistakes Your providers make mistakes That other team are knuckleheads
10. AGENDA ASSUMPTIONS DEVELOPER EXPERIENCE LOVE AT FIRST BYTE ADOPTION DAY TO DAY
11. “Developers are users too” – Keith Casey aka That guy in front of you, right now
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
15. 1. Documentation Ways to deliver documentation PDF - [redacted] HTML - https://www.twilio.com/api
16. 1. Documentation (cont) Let’s get interactive! Swagger - http://docs.clarify.io/api/ (Open API) RAML, JSON Schema, API Blueprint
17. 2. Incomplete/Wrong Docs Helper docs != API docs
18. 3. Getting Started Code
19. 4. Too Much Boilerplate So.. so.. many. It makes me die a little inside.
20. 5. SOAP as the Interface Do I need to say more?
21. 5. SOAP as the Interface I guess I probably should..
22. 5. SOAP as the Interface REST is borrowing $10 from a friend SOAP is getting a mortgage
23. AGENDA ASSUMPTIONS DEVELOPER EXPERIENCE LOVE AT FIRST BYTE ADOPTION DAY TO DAY
24. 6. Illogical/Inconsistencies Accounts Contacts ContactHistories Users ContactGroupings /api/v1/accounts /api/v1/contacts /api/v1/contact_histories ??? ???
25. 6. Illogical/Inconsistencies Accounts Contacts ContactHistories Users ContactGroupings /api/v1/accounts /api/v1/contacts /api/v1/contact_histories /api/v1/users /api/v1/contact_groupings
26. 6. Illogical/Inconsistencies 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
27. 6b. Illogical/Inconsistencies 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
28. 6b. Illogical/Inconsistencies 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
29. 7. Poor Workflow/Modeling Affordances What is the API producer’s goal? What problems/tasks does it makes simple? What do you want to do?
31. 7. Poor Workflow/Modeling Who is the API for? Is this an internal API made public? Is this specifically designed for external use? Where does the API fit in their business? aka - Bolted on or part of their company?
32. 8. Numerous Approaches
33. 9. Authentication Don’t roll your own “new” methods Don’t roll your own “encryption” scheme
34. 9. Authentication Don’t roll your own “new” methods Don’t roll your own “encryption” scheme Please.
35. 9. Authentication Don’t roll your own “new” methods Don’t roll your own “encryption” scheme Please. No, seriously.
36. AGENDA ASSUMPTIONS DEVELOPER EXPERIENCE LOVE AT FIRST BYTE ADOPTION DAY TO DAY
37. 10. Your sh.. stuff is broken What does your uptime look like? Is the API deterministic? (No, seriously..) Are the docs up to date?
38. 11. Error Messages { “response_code”:“404”, “response_msg”:”There was an error.” }
39. 11. Error Messages { “response_code”:“404”, “response_msg”:”Item not found.” }
40. 11. Error Messages { “response_code”:“200”, “error_code”:”11007”, “response_msg”:”Item not found.” }
41. 11. Error Messages { “response_code”:“404”, “error_code”:”11007, “response_msg”:”Item not found.” }
42. 11. Error Messages { “response_code”:“404”, “error_code”:”11007, “response_msg”:”Item not found.”, “more_info”:”http://docs.clarify.io/errors/11007” }
43. 12. Logging & Debugging
44. 12. Logging & Debugging “Building your API Utility Belt” https://speakerdeck.com/caseysoftware/building- your-api-utility-belt
45. AGENDA ASSUMPTIONS DEVELOPER EXPERIENCE LOVE AT FIRST BYTE ADOPTION DAY TO DAY
46. Starting Documentation Consumable Accurate & Complete Examples Simplicity in Code & Interfaces
47. Building Logical & Consistent aka Predictable Designed Workflows vs random junk The One True Way Consistent Payloads Authentication
48. Maintaining Error Messages & Handling Logging & Debugging
49. 12 REASONS YOUR API SUCKS D. KEITH CASEY JR. @CASEYSOFTWARE KEITH@CASEYSOFTWARE.COM
50. Who am I? http://TheAPIDesignBook.com