API Design as an Art

As developers, we are constantly interacting with APIs. Good ones can make feature iterations a breeze, and bad ones can waste hours of developer productivity. But we rarely stop to consider how they fit into our own work or how to be cognizant of potential design pitfalls. Using AutoDispose, an open source reactive tool for automatic stream disposal, as a case study, this talk will evaluate strategies and best practices for iteratively fine tuning real world APIs for better testing and the overall developer experience of your consumers.

Transcript

1. API Design as an
   Art
   Zac Sweers - Uber
   @pandanomic
   

   View Slide

2. aWhat makes ana
   API?
   

   View Slide

3. aWhat makes ana
   API bad?
   

   View Slide

4. View Slide

5. Developer experience
   API Design
   

   View Slide

6. View Slide

7. Developer experience
   API Design
   

   View Slide

8. View Slide

9. View Slide

10. View Slide

11. aWhat makes ana
    API bad?
    

    View Slide

12. What makes an
    API good?
    !
    

    View Slide

13. What makes an
    API good?
    
    

    View Slide

14. View Slide

15. 
    
    ⛏
    
    
    
    
    
    
    

    View Slide

16. Your lib
    Picasso
    Dagger
    ROOM
    Support library
    Internal libs
    Butter Knife
    RxJava
    Kotlin
    
    
    ⛏
    
    
    
    
    
    
    

    View Slide

17. AutoDispose
    

    View Slide

18. AutoDispose
    • RxJava 2 utility for automatic stream
    disposal
    

    View Slide

19. AutoDispose
    • RxJava 2 utility for automatic stream
    disposal
    • Originally built in a side project ~10/2016
    

    View Slide

20. AutoDispose
    • RxJava 2 utility for automatic stream
    disposal
    • Originally built in a side project ~10/2016
    • Mainlined to Uber ~12/2016
    

    View Slide

21. AutoDispose
    • RxJava 2 utility for automatic stream
    disposal
    • Originally built in a side project ~10/2016
    • Mainlined to Uber ~12/2016
    • Open sourced 3/2017
    

    View Slide

22. Observable.just(1)
    .subscribe()
    

    View Slide

23. apiRequest()
    .subscribe()
    

    View Slide

24. apiRequest() // 200+ ms
    .subscribe()
    

    View Slide

25. apiRequest() // 200+ ms
    .subscribeOn(io())
    .observeOn(mainThread())
    .subscribe()
    

    View Slide

26. apiRequest() // 200+ ms
    .subscribeOn(io())
    .observeOn(mainThread())
    .subscribe()
    // DetailActivity.kt
    Memory
    leak
    

    View Slide

27. val disposable = apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .subscribe()
    

    View Slide

28. val disposable = apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .subscribe()
    // Later
    disposable.dispose()
    

    View Slide

29. val disposable = apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .subscribe()
    

    View Slide

30. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .subscribe()
    

    View Slide

31. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .to(AutoDispose.with(this).forObservable())
    .subscribe()
    

    View Slide

32. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .to(AutoDispose
    .with(this) // Scope
    .forObservable()) // Type
    .subscribe()
    

    View Slide

33. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .to(AutoDispose
    .with(this) // Scope
    .forObservable()) // Type
    .subscribe()
    

    View Slide

34. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .to(AutoDispose
    .with(this) // Scope
    .forObservable()) // Type
    .subscribe()
    

    View Slide

35. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .to(AutoDispose
    .with(this) // Scope
    .forObservable()) // Type
    .subscribe()
    

    View Slide

36. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .to(AutoDispose
    .with(this) // Scope
    .forObservable()) // Type
    .subscribe()
    

    View Slide

37. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .to(AutoDispose
    .with(this)
    .forObservable())
    .subscribe()
    

    View Slide

38. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .to(AutoDispose
    .with(Maybe.never())
    .forObservable())
    .subscribe()
    

    View Slide

39. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .to(AutoDispose
    .with(this)
    .forObservable())
    .subscribe()
    

    View Slide

40. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .to(AutoDispose
    .with(this) // ScopeProvider
    .forObservable())
    .subscribe()
    

    View Slide

41. interface ScopeProvider {
    fun requestScope(): Maybe<*>
    }
    

    View Slide

42. interface LifecycleScopeProvider {
    fun correspondingEvents(): Function
    fun peekLifecycle(): E
    fun lifecycle(): Observable
    }
    

    View Slide

43. interface ScopeProvider {
    fun requestScope(): Maybe<*>
    }
    

    View Slide

44. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .to(AutoDispose
    .with(this) // ScopeProvider
    .forObservable())
    .subscribe()
    

    View Slide

45. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .subscribe()
    

    View Slide

46. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .subscribe()
    .disposeOn(lifecycle)
    

    View Slide

47. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .subscribe {
    // Stuff
    }
    .disposeOn(lifecycle)
    

    View Slide

48. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .subscribe {
    // Stuff
    // Stuff
    // Stuff
    // Stuff
    // Stuff
    // Stuff
    }
    

    View Slide

49. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .subscribe {
    // Stuff
    // Stuff
    // Stuff
    // Stuff
    // Stuff
    // Stuff
    }
    .disposeOn(lifecycle)
    

    View Slide

50. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .subscribe({ r ->
    // Handle response
    }) { error: Throwable ->
    // Stuff
    // Stuff
    }
    .disposeOn(lifecycle)
    

    View Slide

51. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .delaySubscription(attaches())
    .subscribe()
    .disposeOn(lifecycle)
    

    View Slide

52. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .delaySubscription(attaches())
    .subscribe(myObserver)
    .disposeOn(lifecycle)
    

    View Slide

53. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .delaySubscription(attaches())
    .subscribe(myObserver)
    .disposeOn(lifecycle)
    

    View Slide

54. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .subscribe()
    

    View Slide

55. apiRequest()
    .subscribeOn(io())
    .observeOn(mainThread())
    .subscribe(BoundObservers.forObservable(lifecycle)
    .onNext(...)
    .create())
    

    View Slide

56. .subscribe(BoundObservers.forObservable(lifecycle)
    .onNext(...)
    .create())
    

    View Slide

57. .subscribe(BoundObservers.forObservable(lifecycle)
    .onNext(...)
    .create())
    

    View Slide

58. .subscribe(BoundObservers.forObservable(lifecycle)
    .onNext(...)
    .create())
    

    View Slide

59. .subscribe(BoundObservers.forObservable(lifecycle)
    .onNext(...)
    .create())
    

    View Slide

60. .subscribe(BoundObservers.forObservable(lifecycle)
    .onNext(...)
    .onError(...)
    .create())
    

    View Slide

61. .subscribe(BoundObservers.forObservable(lifecycle)
    .onNext(...)
    .create())
    

    View Slide

62. .subscribe(BoundObservers.forObservable(lifecycle)
    .onNext(...)
    .create())
    

    View Slide

63. .subscribe(BoundObservers.forObservable(lifecycle)
    .onNext(...)
    .onError(...)
    .create())
    

    View Slide

64. .subscribe(BoundObservers.forObservable(lifecycle)
    .onNext(...)
    .onError(...)
    .onComplete(...)
    .create())
    

    View Slide

65. .subscribe()
    

    View Slide

66. .subscribe(BoundObservers.forObservable(lifecycle)
    .create())
    

    View Slide

67. .subscribe(BoundObservers.forObservable(lifecycle)
    .create())
    

    View Slide

68. .subscribe(BoundObservers.forObservable(lifecycle)
    .create())
    

    View Slide

69. .subscribe(BoundObservers.forObservable(lifecycle)
    .onNext(Object o -> ???) // ಠ_ಠ
    .create())
    

    View Slide

70. .subscribe(BoundObservers.forObservable(lifecycle)
    .onNext(Object o -> ???) // ಠ_ಠ
    .create())
    

    View Slide

71. .subscribe(BoundObservers.forObservable(lifecycle)
    .onNext(Response r -> ...) // :D
    .create())
    

    View Slide

72. .subscribe(BoundObservers.forObservable(lifecycle)
    .create())
    

    View Slide

73. ResponseObserver o = ResponseObserver()
    .subscribe(BoundObservers.forObservable(lifecycle)
    .create())
    

    View Slide

74. class ResponseObserver : BoundObserver() {
    // :(
    }
    

    View Slide

75. ResponseObserver o = ResponseObserver()
    .subscribe(BoundObservers.forObservable(lifecycle)
    .create())
    

    View Slide

76. ResponseObserver o = ResponseObserver()
    PublishSubject sub = PublishSubject.create()
    .subscribe(BoundObservers.forObservable(lifecycle)
    .create())
    

    View Slide

77. PublishSubject sub = PublishSubject.create()
    .subscribe(BoundObservers.forObservable(lifecycle)
    .create())
    
    

    View Slide

78. PublishSubject sub = PublishSubject.create()
    .subscribe(BoundObservers.forObservable(lifecycle)
    .around(sub))
    
    

    View Slide

79. PublishSubject sub = PublishSubject.create()
    .subscribe(BoundObservers.forObservable(lifecycle)
    .around(sub))
    
    

    View Slide

80. PublishSubject sub = PublishSubject.create()
    .subscribe(BoundObservers.forObservable(lifecycle)
    .onNext(...)
    .around(sub))
    
    

    View Slide

81. PublishSubject sub = PublishSubject.create()
    .subscribe(BoundObservers.forObservable(lifecycle)
    .onNext(...)
    .around(sub))
    
    

    View Slide

82. PublishSubject sub = PublishSubject.create()
    .subscribe(BoundObservers.forObservable(lifecycle)
    .onNext(...)
    .onNext(...)
    .onNext(...)
    .onNext(...)
    .onNext(...)
    .onNext(...)
    .onNext(...)
    .around(sub))
    

    View Slide

83. .subscribe(BoundObservers.forObservable(lifecycle)
    .create())
    

    View Slide

84. .subscribe(AutoDispose.forObservable(lifecycle)
    .create())
    

    View Slide

85. .subscribe(AutoDispose.forObservable(lifecycle)
    .around(...))
    

    View Slide

86. fun around(o: Observer)
    fun around(c: Consumer)
    fun around(c: Consumer, e: Consumer)
    fun around(c: Consumer, e: Consumer, a: Action)
    // Etc
    

    View Slide

87. fun around(o: Observer)
    fun around(c: Consumer)
    fun around(c: Consumer, e: Consumer)
    fun around(c: Consumer, e: Consumer, a: Action)
    fun empty()
    // Etc
    

    View Slide

88. interface AroundClause {
    fun around(o: Observer)
    fun around(c: Consumer)
    fun around(c: Consumer, e: Consumer)
    fun around(c: Consumer, e: Consumer, a: Action)
    fun empty()
    // Etc
    }
    

    View Slide

89. ResponseObserver o = new ResponseObserver()
    .subscribe(AutoDispose.forObservable(lifecycle)
    .around(o))
    V2
    : AroundClause
    

    View Slide

90. ResponseObserver o = new ResponseObserver()
    .subscribe(AutoDispose.forObservable(lifecycle)
    .around(o))
    

    View Slide

91. ResponseObserver o = new ResponseObserver()
    .subscribe(AutoDispose.observable()
    .scopeWith(lifecycle)
    .around(o))
    V3
    

    View Slide

92. ResponseObserver o = new ResponseObserver()
    .subscribe(AutoDispose.observable()
    .scopeWith(scope)
    .around(o))
    V3
    

    View Slide

93. ResponseObserver o = new ResponseObserver()
    .subscribe(AutoDispose.observable()
    .scopeWith(scope)
    .around(o))
    

    View Slide

94. ResponseObserver o = new ResponseObserver()
    .subscribe(AutoDispose.observable()
    .scopeWith(scope)
    .around(o))
    

    View Slide

95. ResponseObserver o = new ResponseObserver()
    .subscribe(AutoDispose.observable()
    .scopeWith(scope)
    .around(o))
    

    View Slide

96. ResponseObserver o = new ResponseObserver()
    .subscribe(AutoDispose.observable()
    .scopeWith(scope)
    .around(o))
    

    View Slide

97. interface AroundClause {
    fun around(o: Observer)
    fun around(c: Consumer)
    fun around(c: Consumer, e: Consumer)
    fun around(c: Consumer, e: Consumer, a: Action)
    fun empty()
    // Etc
    }
    

    View Slide

98. interface AroundClause {
    fun around(o: Observer)
    fun around(c: Consumer)
    fun around(c: Consumer, e: Consumer)
    fun around(c: Consumer, e: Consumer, a: Action)
    fun empty()
    // Etc
    }
    

    View Slide

99. ResponseObserver o = new ResponseObserver()
    .subscribe(AutoDispose.observable()
    .scopeWith(scope)
    .around(o))
    

    View Slide

100. ResponseObserver o = new ResponseObserver()
     .subscribe(AutoDispose.observable()
     .scopeWith(scope)
     .around(o))
     

     View Slide

101. ResponseObserver o = new ResponseObserver()
     .subscribe(AutoDispose.observable()
     .scopeWith(scope)
     .around(new Consumer() {
     // Impl
     }))
     

     View Slide

102. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .subscribe(AutoDispose.observable()
     .scopeWith(scope)
     .around(new Consumer() {
     // Impl
     }))
     V4
     

     View Slide

103. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .subscribe(AutoDispose.observable()
     .scopeWith(scope)
     .around(new Consumer() {
     // Impl
     }))
     

     View Slide

104. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .subscribe(AutoDispose.observable()
     .scopeWith(scope)
     .around(new Consumer() {
     @Override
     public void accept(Response r) {
     handleResponse(r)
     }
     }))
     

     View Slide

105. .to()
     

     View Slide

106. .to(new Function, ???>() {})
     

     View Slide

107. .to(new Function, AroundClause>() {})
     

     View Slide

108. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .subscribe(AutoDispose.observable()
     .scopeWith(scope)
     .around(new Consumer() {
     @Override
     public void accept(Response r) {
     handleResponse(r)
     }x
     }))
     

     View Slide

109. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .to(???)
     .subscribe(AutoDispose.observable()
     .scopeWith(scope)
     .around(new Consumer() {
     @Override
     public void accept(Response r) {
     handleResponse(r)
     }x
     }))
     

     View Slide

110. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .to(???)
     .around(new Consumer() {
     @Override
     public void accept(Response r) {
     handleResponse(r)
     }x
     }))
     

     View Slide

111. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .to(AutoDispose.observable()
     .scopeWith(scope))
     .around(new Consumer() {
     @Override
     public void accept(Response r) {
     handleResponse(r)
     }x
     }))
     

     View Slide

112. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .to(AutoDispose.observable()
     .scopeWith(scope))
     .around(new Consumer() {
     @Override
     public void accept(Object r) {
     handleResponse(r)
     }x
     }))
     

     View Slide

113. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .to(AutoDispose.observable()
     .scopeWith(scope))
     .around(new Consumer() {
     @Override
     public void accept(Object r) {
     // (╯°□°）╯︵ ┻━┻
     }x
     }))
     

     View Slide

114. class ObservableScoper
     implements Function, AroundClause> {
     }v
     

     View Slide

115. class ObservableScoper
     implements Function, AroundClause> {
     ObservableScoper(Maybe> scope) {
     // ...
     }a
     }v
     

     View Slide

116. class ObservableScoper
     implements Function, AroundClause> {
     ObservableScoper(Maybe> scope) {
     // ...
     }a
     @Override
     public AroundClause apply(Observable o) {
     }b
     }v
     

     View Slide

117. class ObservableScoper
     implements Function, AroundClause> {
     ObservableScoper(Maybe> scope) {
     // ...
     }a
     @Override
     public AroundClause apply(Observable o) {
     return new AroundClause() {
     // ...
     }c
     }b
     }v
     

     View Slide

118. class ObservableScoper
     implements Function, AroundClause> {
     ObservableScoper(Maybe> scope) {
     // ...
     }a
     @Override
     public AroundClause apply(Observable o) {
     return new AroundClause() {
     // ...
     }c
     }b
     }v
     

     View Slide

119. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .to(new ObservableScoper(scope))
     .around(new Consumer() {
     @Override
     public void accept(Response r) {
     handleResponse(r)
     }
     }))
     

     View Slide

120. interface AroundClause {
     fun around(o: Observer)
     fun around(c: Consumer)
     fun around(c: Consumer, e: Consumer)
     fun around(c: Consumer, e: Consumer, a: Action)
     fun empty()
     // Etc
     }
     

     View Slide

121. interface SubscribeProxy {
     fun around(o: Observer)
     fun around(c: Consumer)
     fun around(c: Consumer, e: Consumer)
     fun around(c: Consumer, e: Consumer, a: Action)
     fun empty()
     // Etc
     }
     

     View Slide

122. interface SubscribeProxy {
     fun subscribe(o: Observer)
     fun subscribe(c: Consumer)
     fun subscribe(c: Consumer, e: Consumer)
     fun subscribe(c: Consumer, e: Consumer, a: Action)
     fun empty()
     // Etc
     }
     

     View Slide

123. interface SubscribeProxy {
     fun subscribe(o: Observer)
     fun subscribe(c: Consumer)
     fun subscribe(c: Consumer, e: Consumer)
     fun subscribe(c: Consumer, e: Consumer, a: Action)
     fun subscribe()
     // Etc
     }
     

     View Slide

124. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .to(new ObservableScoper(scope))
     .around(new Consumer() {
     @Override
     public void accept(Response r) {
     handleResponse(r)
     }
     }))
     

     View Slide

125. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .to(new ObservableScoper(scope))
     .subscribe(new Consumer() {
     @Override
     public void accept(Response r) {
     handleResponse(r)
     }
     }))
     

     View Slide

126. –Nick Butcher, and probably other people
     “If it looks right, it is right.”
     

     View Slide

127. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .to(new ObservableScoper(scope))
     .subscribe(newxConsumer() {
     @Override
     public void accept(Response r) {
     handleResponse(r)
     }x
     }))
     V5
     

     View Slide

128. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .to(AutoDispose.with(scope).forObservable())
     .subscribe(newxConsumer() {
     @Override
     public void accept(Response r) {
     handleResponse(r)
     }x
     }))
     

     View Slide

129. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .to(AutoDispose.with(scope).forObservable())
     .subscribe(new Consumer() {
     @Override
     public void accept(Response r) {
     handleResponse(r)
     }x
     }))
     

     View Slide

130. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .to(AutoDispose.forObservable(scope))
     .subscribe(new Consumer() {
     @Override
     public void accept(Response r) {
     handleResponse(r)
     }x
     }))
     

     View Slide

131. View Slide

132. https://youtrack.jetbrains.com/issue/
     IDEA-179864
     

     View Slide

133. apiRequest()
     .subscribeOn(io())
     .observeOn(mainThread())
     .to(AutoDispose.forObservable(scope))
     .subscribe(new Consumer() {
     @Override
     public void accept(Response r) {
     handleResponse(r)
     }x
     }))
     

     View Slide

134. aWhat makes ana
     API good?
     !
     

     View Slide

135. “Prefer exposing interfaces”
     

     View Slide

136. “Prefer exposing interfaces”
     interface SubscribeProxy {
     fun subscribe(o: Observer)
     fun subscribe(c: Consumer)
     fun subscribe(c: Consumer, e: Consumer)
     fun subscribe(c: Consumer, e: Consumer, a: Action)
     fun subscribe()
     // Etc
     }
     

     View Slide

137. “Prefer composition in accepting
     external implementations. Inheritance
     can be inconvenient.”
     

     View Slide

138. “Prefer composition in accepting
     external implementations. Inheritance
     can be inconvenient.”
     class ResponseObserver : BoundObserver() {
     // :(
     }
     PublishSubject sub = PublishSubject.create()
     
     

     View Slide

139. “Prefer final by default”
     

     View Slide

140. “Identify footguns”
     

     View Slide

141. “Identify footguns”
     .subscribe(BoundObservers.forObservable(lifecycle)
     .onNext(...)
     .onNext(...)
     .onNext(...)
     .onNext(...)
     .onNext(...)
     .onNext(...)
     .onNext(...)
     .around(sub))
     

     View Slide

142. “Dependency on lint should be avoided”
     

     View Slide

143. “Dependency on lint should be avoided”
     

     View Slide

144. “IDE experience matters”
     

     View Slide

145. “IDE experience matters”
     .around(new Consumer() {
     @Override
     public void accept(Object r) {
     // (╯°□°）╯︵ ┻━┻
     }x
     }))
     

     View Slide

146. “Crack eggs, make omelettes”
     V4
     V5
     V0
     V3
     V1
     

     View Slide

147. View Slide

148. Questions?
     Zac Sweers - Uber
     @pandanomic
     

     View Slide