APIs on the Scale of Decades

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.

1b5863cbb2d0009e78eaa85ea89fe2a6?s=128

garyfleming

August 07, 2018
Tweet

Transcript

  1. APIS ON THE SCALE OF DECADES @GARYFLEMING

  2. None
  3. WHY ARE THEY REGRETTABLE? > Hard to see how to

    use, > Assumptions that turn out to be wrong, > Poorly explained domain concepts.
  4. None
  5. None
  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?

  11. None
  12. None
  13. None
  14. None
  15. THE STAR IS A SIGNAL

  16. AFFORDANCE HOW AN ACTOR SEES THE ACTIONAL PROPERTIES OF THE

    WORLD
  17. None
  18. None
  19. None
  20. None
  21. THE TREE DIDN'T TELL THEM A THING.

  22. APIS THO?

  23. PERCEIVED AFFORDANCE

  24. None
  25. PERCEIVED AFFORDANCE

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

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

  78. None
  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/