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.

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