APIs on the Scale of Decades

"APIs are hard. They are pretty much ship now, regret later." -- Chet Haase.

What do Greek philosophy, early video games, and Japanese bullet trains tell us about how we should design our APIs?

Writing any old API is easy. Writing an API that can evolve to meet your needs over the coming months, years, and even decades; now that's hard. We'll look at some common practices and try to see where they go wrong, some misunderstood techniques and how to use them better, and some less common practices that might be useful.

Let me give you some good advice that'll help you evolve your APIs, and some big ideas that might provoke some interesting thoughts.

Transcript

1. APIS ON THE SCALE OF DECADES @GARYFLEMING
3. WHY ARE THEY REGRETTABLE? > Hard to see how to use, > Assumptions that turn out to be wrong, > Poorly explained domain concepts.
6. REALLY. THINK.
7. WEB APIS VS CODE APIS
8. A LONG TIME AGO...
9. > Machine and human readable > Changeable > Easy to Navigate > Easy to Update Data > Lightweight Structures > Optional Types > Existing tooling
10. PART I: WHAT CAN YOU AFFORD?
15. THE STAR IS A SIGNAL
16. AFFORDANCE HOW AN ACTOR SEES THE ACTIONAL PROPERTIES OF THE WORLD
21. THE TREE DIDN'T TELL THEM A THING.
22. APIS THO?
23. PERCEIVED AFFORDANCE
25. PERCEIVED AFFORDANCE
27. > You don't necessarily save to a disk.
28. > You don't necessarily save to a disk. > If you did, it wouldn't be a floppy.
29. > You don't necessarily save to a disk. > If you did, it wouldn't be a floppy. > If it was a floppy disk, it wouldn't just be a drawing.
30. The Uncomfortable
31. CAVEAT!
32. PART 2: THE FORM OF THINGS
34. EXAMPLE: CAT > Given Name > Family Name > Birth Date > Address
35. EYES > ! Normal, > " Tears, > # Lovehearts, > $ Shocked
36. PART 3: NO REST FOR THE WICKED
37. ROY FIELDING
38. "Architectural Styles and the Design of Network-based Software Architectures."
39. REPRESENTATIO NAL STATE TRANSFER (REST)
40. REP·RE·SEN·TA· TION·AL
41. BACK TO REST "What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint?"
42. HYPERTEXT IS... "... the simultaneous presentation of information and controls such that the information becomes the affordance through which the user [...] obtains choices and selects actions."
43. WUT?
44. INFORMATION + CONTROLS = BETTER API
45. ACTION CONTEXTUALISES INFORMATION CONTEXTUALISES ACTION
46. ACTION CONTEXTUALISES INFORMATION CONTEXTUALISES ACTION > $100. Want to transfer (up to $100)?
47. ACTION CONTEXTUALISES INFORMATION CONTEXTUALISES ACTION > $100. Want to transfer (up to $100)? > $70
48. ACTION CONTEXTUALISES INFORMATION CONTEXTUALISES ACTION > $100. Want to transfer (up to $100)? > $70 > $30. Want to transfer (up to $30)?
49. ACTION CONTEXTUALISES INFORMATION CONTEXTUALISES ACTION > $100. Want to transfer (up to $100)? > $70 > $30. Want to transfer (up to $30)? > 30
50. ACTION CONTEXTUALISES INFORMATION CONTEXTUALISES ACTION > $100. Want to transfer (up to $100)? > $70 > $30. Want to transfer (up to $30)? > 30 > $0. Nothing left to transfer
51. EXAMPLES PLZ
52. GENERIC VS SPECIFIC CONTROLS
53. COLLECTION /cats !"#$%&'()*+ !"#$%&'()!" !"#$%&'()!" !"#$%&'()*+
54. COLLECTION (NAVIGATE) /cats !"#$%&'()*+ > Self > Start or End > [non-paging controls] > Next
55. COLLECTION (NAVIGATE 2) /cats?page=2 !"#$%&'()!" > Self > Start or End > Prev or Next > [non-paging controls]
56. FILTER /cats?eyes=tears!""""!" > [paging controls] > Eyes=<some eye type>
57. SORT /cats?sort=orientation !!!!!"#$%&' > [other paging controls] > sort=<some criteria>
58. WHY GENERIC CONTROLS? > Standardised across collections > Surprisingly poorly implemented by clients > Easy burden to take on
59. SPECIFIC: TEXT ADVENTURES
60. DOMAIN KNOWLEDGE IS OK ! ->
61. ALEXA SEARCH FOR...
62. AFFORDANCE IS DOCUMENTATION
63. PART 4: CHANGE
64. SHIP OF THESEUS
65. SHIP OF THESEUS > Mereological theory of identity
66. SHIP OF THESEUS > Mereological theory of identity > Spatio-temporal continuity theory
67. IT'S A VERSIONING PROBLEM
68. BULLET TRAINS
69. BIOMIMICRY
70. OWL V2
71. AFFORDANCE TRUMPS VERSIONING
72. NO VERSION?
73. YOU DEAL WITH THIS EVERY DAY
74. CHANGE IS INEVITABLE SO CHANGE
75. PART 5: TESTING
76. BUILD FOR CHANGE
77. CONSUMER- DRIVEN CONTRACTS
79. FUZZERS
80. FUZZERS > Modify parts without contract coverage
81. FUZZERS > Modify parts without contract coverage > Scramble links
82. FUZZERS > Modify parts without contract coverage > Scramble links > Add in dummy data
83. BREAK ASSUMPTIONS. THINK AFFORDANCE.
84. PART 6: A NEW OLD API
85. > Affordances > The Forms of Things > Rest being about controls > Versioning > Testing (if I had time)
86. WHAT ELSE DO WE WANT? > Easy to Navigate > Easy to Update Data > Lightweight Structures > Optional Types > Existing tooling
87. JSON... WHY?
88. XML WAS PROBLEMATIC
89. XML WAS PROBLEMATIC > Verbose
90. XML WAS PROBLEMATIC > Verbose > No real structures
91. XML WAS PROBLEMATIC > Verbose > No real structures > Arbitrarily complex and extensible
92. XML WAS PROBLEMATIC > Verbose > No real structures > Arbitrarily complex and extensible > etc
93. WHAT SOLVES THE PROBLEM?
94. HTML5 HAS IT ALL
95. HTML5 HAS IT ALL
96. HTML5 HAS IT ALL > Links
97. HTML5 HAS IT ALL > Links > Forms
98. HTML5 HAS IT ALL > Links > Forms > Structures
99. HTML5 HAS IT ALL > Links > Forms > Structures > Types
100. HTML5 HAS IT ALL > Links > Forms > Structures > Types > Tooling
101. YOU DEAL WITH THIS EVERY DAY
102. WRITE YOUR APIS USING HTML5
103. FOR SRS?
104. THANK YOU @GARYFLEMING
105. THANK YOU @GARYFLEMING GITHUB.COM/ GARYFLEMING/APIS-FOR- DECADES/