1. Lessons
on API design
Andrey Salomatin
@flpvsk

3. API affects
—What you can and can not do
—How does it perform
—How easy it is to make a mistake
2018-12-02 @flpvsk @growitconf 3

4. Why look at well-known projects?
—To understand how the systems we use work
—To learn techniques we can apply in our projects
—To improve our thinking processes
2018-12-02 @flpvsk @growitconf 4

5. 1: A pixel
is not
a pixel2018-12-02 @flpvsk @growitconf 5

6. Poor abstractions
limit what we can do
using the API.
2018-12-02 @flpvsk @growitconf 6

7. 2018-12-02 @flpvsk @growitconf 7

8. x = ?
1. h1 / 2
2. (h1 - h2) / 2
3. (h1 + h2) / 2
2018-12-02 @flpvsk @growitconf 8

9. x = ?
2. (h1 - h2) / 2
2018-12-02 @flpvsk @growitconf 9

10. CSS
.container {
display: flex;
align-items: center;
}
2018-12-02 @flpvsk @growitconf 10

11. 2018-12-02 @flpvsk @growitconf 11

12. x = ?
1. h3 * round(
(h1 - h2) / (2 * h3))
2. h3 * (h1 - h2) / 2
3. h3 * floor(
(h1 + h2) / 2)
2018-12-02 @flpvsk @growitconf 12

13. x = ?
1. h3 * round(
(h1 - h2) / (2 * h3))
2018-12-02 @flpvsk @growitconf 13

14. Center element within a grid
—CSS?
—iOS Auto Layout?
—Android Layout?
2018-12-02 @flpvsk @growitconf 14

15. Vertical rhythm
2018-12-02 @flpvsk @growitconf 15

16. Testing layout & paint
requires spinning off
a simulator or a browser
2018-12-02 @flpvsk @growitconf 16

17. A pixel
is not
a pixel2018-12-02 @flpvsk @growitconf 17

18. Browser vendors' in the early 90s:
—WWW is for documents
—Each browser will decide how to best display
pages to their users
2018-12-02 @flpvsk @growitconf 18

19. 19

20. Browser vendors' in the early 90s:
—WWW is for documents
—Each browser will decide how to display pages
—Seems like publishers want styling
2018-12-02 @flpvsk @growitconf 20

21. …the style of a document
couldn't be designed
by either the author
or the reader
on their own…
2018-12-02 @flpvsk @growitconf 21

22. …their wishes have to be
combined, or cascaded,
in some way.
2018-12-02 @flpvsk @growitconf 22

23. 23

24. 2018-12-02 @flpvsk @growitconf 24

25. Flutter design principles
—Layered API
—Access to Layout and Paint phases
—Full control over what is drawn on the screen
2018-12-02 @flpvsk @growitconf 25

26. Vertical rhythm in Flutter
Offset getPositionForChild(
Size containerSize,
Size childSize
)
2018-12-02 @flpvsk @growitconf 26

27. Vertical rhythm in Flutter
Offset getPositionForChild(
Size containerSize,
Size childSize
) {
final h1 = containerSize.height;
final h2 = childSize.height;
final h3 = rowHeight;
final rowsCount = ((h1 - h2) / (2 * h3)).round();
return Offset(0, rowsCount * h3);
}
2018-12-02 @flpvsk @growitconf 27

28. Vertical rhythm in Flutter
Offset getPositionForChild(
Size containerSize,
Size childSize
) {
final h1 = containerSize.height;
final h2 = childSize.height;
final h3 = rowHeight;
final rowsCount = ((h1 - h2) / (2 * h3)).round();
return Offset(0, rowsCount * h3);
}
2018-12-02 @flpvsk @growitconf 27

29. Geometry
x = h3 * round(
(h1 - h2) / (2 * h3)
)
2018-12-02 @flpvsk @growitconf 28

30. 2018-12-02 @flpvsk @growitconf 29

31. Properly layered API
gives freedom to build for
custom usecases.
2018-12-02 @flpvsk @growitconf 30

32. 31

33. 32

34. 33

35. 34

36. 35

37. 36

38. 37

39. 38

40. 39

41. 40

42. 2: Simple
or easy2018-12-02 @flpvsk @growitconf 41

43. Programming language
designers balance
cognitive load
and capabilities.
2018-12-02 @flpvsk @growitconf 42

44. 43

45. Good abstractions
help API users
avoid mistakes.
2018-12-02 @flpvsk @growitconf 44

46. Working with
concurrency
2018-12-02 @flpvsk @growitconf 45

47. 46

48. 2018-12-02 @flpvsk @growitconf 47

49. Concurrency basics in Java
synchronized method() {}
synchronized (object) {}
Object.wait();
Object.notify();
Object.notifyAll();
2018-12-02 @flpvsk @growitconf 48

50. Actual concurrency in Java
—432 pages
—18cm x 3cm x 23cm
—635g
49

51. 50

52. Correctness
is impossible
to enforce.
2018-12-02 @flpvsk @growitconf 51

53. 2018-12-02 @flpvsk @growitconf 52

54. Concurrency basics in Rust
2018-12-02 @flpvsk @growitconf 53

55. Concurrency basics in Rust
—New concept of Borrow Checker
2018-12-02 @flpvsk @growitconf 53

56. Concurrency basics in Rust
—New concept of Borrow Checker
—Thread safety enforced by the compiler
2018-12-02 @flpvsk @growitconf 53

57. Concurrency basics in Rust
—New concept of Borrow Checker
—Thread safety enforced by the compiler
—Custom primitives with Send and Sync traits
2018-12-02 @flpvsk @growitconf 53

58. Expressive API
requires
more effort
from the person
adopting it.
2018-12-02 @flpvsk @growitconf 54

59. Choose what's important
and make it
hard to get wrong.
2018-12-02 @flpvsk @growitconf 55

60. Other examples
—RPC (free for all) vs
REST (unification) vs
GraphQL (flexibility on the client)
—Ethereum Solidity (ffa) vs
Bamboo (understanding state & transitions)
2018-12-02 @flpvsk @growitconf 56

61. 3: Tree
that scales2018-12-02 @flpvsk @growitconf 57

62. API is
a performance
bottleneck.
2018-12-02 @flpvsk @growitconf 58

63. 59

64. 60

65. 61

66. 62

67. 63

68. 64

69. 65

70. 66

71. 1h talk in Full-HD: 3.6GB
Chunk size Chunks count Metadata size
2MB 1800 >36KB
1MB 3516 >70KB
512KB 7032 >140KB
2018-12-02 @flpvsk @growitconf 67

72. 10h conference in Full-HD: 36GB
Chunk size Chunks count Metadata size
2MB 18000 >360KB
1MB 35160 >700KB
512KB 70320 >1.4MB
2018-12-02 @flpvsk @growitconf 68

73. 69

74. bittorent scaling issues
—Size of metadata
—Size of chunks
2018-12-02 @flpvsk @growitconf 70

76. Dat protocol
Peer-to-peer
versioned
data sharing
2018-12-02 @flpvsk @growitconf 72

77. Dat protocol
Decentralized
open-source
analog of Dropbox
2018-12-02 @flpvsk @growitconf 73

78. Dat protocol
—Started as a way to exchange scientific data sets
—Growing as the protocol for p2p web
—Can be used to share TBs of dynamic data
2018-12-02 @flpvsk @growitconf 74

79. 75

80. 76

81. 77

82. 78

83. 79

84. 80

85. 81

86. 82

87. 83

88. 84

89. 85

90. 86

91. 87

92. Metadata size
—Bittorent: O(n)
—Dat: O(log(n))
n – number of chunks
2018-12-02 @flpvsk @growitconf 88

93. API
is the ultimate
performance bottleneck
2018-12-02 @flpvsk @growitconf 89

94. Other examples
—HTTP/1 and HTTP/2
—Bitcoin core and Lightning network
2018-12-02 @flpvsk @growitconf 90

95. 4: The only
const is
change2018-12-02 @flpvsk @growitconf 91

96. Time and change are
API-designers'
worst nightmares.
2018-12-02 @flpvsk @growitconf 92

97. 93

98. REST API
POST '/:personId/posts'
PUT '/:personId/posts/:postId'
GET '/:personId/posts'
2018-12-02 @flpvsk @growitconf 94

99. 95

100. 96

101. Creating new post
!
--> POST { text: 'All frameworks have tradeoffs!' } '/bob/posts'
"
<-- { id: 'post-1' }
2018-12-02 @flpvsk @growitconf 97

102. 98

103. 99

104. Sharing post
!
--> POST { share: 'post-1', text: 'YES!!' } '/alice/posts'
"
<-- { id: 'post-2' }
2018-12-02 @flpvsk @growitconf 100

105. 101

106. Updating post
!
--> PUT { text: 'Serverless is a lie!' } '/bob/posts/post-1'
"
<-- { ok: true }
2018-12-02 @flpvsk @growitconf 102

107. 103

109. 105

110. REST assumptions
2018-12-02 @flpvsk @growitconf 106

111. REST assumptions
—Everything is a resource
2018-12-02 @flpvsk @growitconf 106

112. REST assumptions
—Everything is a resource
—Resources have unique identifiers
2018-12-02 @flpvsk @growitconf 106

113. REST assumptions
—Everything is a resource
—Resources have unique identifiers
—Resources can change over time*
2018-12-02 @flpvsk @growitconf 106

114. Alternative
assumptions
2018-12-02 @flpvsk @growitconf 107

115. Alternative assumptions
2018-12-02 @flpvsk @growitconf 108

116. Alternative assumptions
—Objects (facts) do not change over time
2018-12-02 @flpvsk @growitconf 108

117. Alternative assumptions
—Objects (facts) do not change over time
—References (labels) can change over time
2018-12-02 @flpvsk @growitconf 108

118. 109

119. 110

120. 111

121. 2018-12-02 @flpvsk @growitconf 112

122. 113

123. The concepts of
time and change
are hard to get right.
2018-12-02 @flpvsk @growitconf 114

124. Separate facts
from labels,
snapshots
from references.
2018-12-02 @flpvsk @growitconf 115

125. Systems that get it right
—CouchDB, Datomic
—bittorent, Dat, IPFS
—Blockchain-based projects
—Event-sourcing-based projects
2018-12-02 @flpvsk @growitconf 116

126. Summary
2018-12-02 @flpvsk @growitconf 117

127. API design
is hard.
2018-12-02 @flpvsk @growitconf 118

128. API affects
—What you can and can not do
—How does it perform
—How easy it is to make a mistake
2018-12-02 @flpvsk @growitconf 119

129. Learn good desgin
from systems
you use.
2018-12-02 @flpvsk @growitconf 120

130. Listen to
code podcast.
2018-12-02 @flpvsk @growitconf 121

131. THE END
2018-12-02 @flpvsk @growitconf 122