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
2. aWhat makes ana API?
3. aWhat makes ana API bad?
5. Developer experience API Design
7. Developer experience API Design
11. aWhat makes ana API bad?
12. What makes an API good? !
13. What makes an API good?
15. ⛏
16. Your lib Picasso Dagger ROOM Support library Internal libs Butter Knife RxJava Kotlin ⛏
17. AutoDispose
18. AutoDispose • RxJava 2 utility for automatic stream disposal
19. AutoDispose • RxJava 2 utility for automatic stream disposal • Originally built in a side project ~10/2016
20. AutoDispose • RxJava 2 utility for automatic stream disposal • Originally built in a side project ~10/2016 • Mainlined to Uber ~12/2016
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
22. Observable.just(1) .subscribe()
23. apiRequest() .subscribe()
24. apiRequest() // 200+ ms .subscribe()
25. apiRequest() // 200+ ms .subscribeOn(io()) .observeOn(mainThread()) .subscribe()
26. apiRequest() // 200+ ms .subscribeOn(io()) .observeOn(mainThread()) .subscribe() // DetailActivity.kt Memory leak
27. val disposable = apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .subscribe()
28. val disposable = apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .subscribe() // Later disposable.dispose()
29. val disposable = apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .subscribe()
30. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .subscribe()
31. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose.with(this).forObservable()) .subscribe()
32. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose .with(this) // Scope .forObservable()) // Type .subscribe()
33. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose .with(this) // Scope .forObservable()) // Type .subscribe()
34. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose .with(this) // Scope .forObservable()) // Type .subscribe()
35. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose .with(this) // Scope .forObservable()) // Type .subscribe()
36. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose .with(this) // Scope .forObservable()) // Type .subscribe()
37. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose .with(this) .forObservable()) .subscribe()
38. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose .with(Maybe.never()) .forObservable()) .subscribe()
39. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose .with(this) .forObservable()) .subscribe()
40. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose .with(this) // ScopeProvider .forObservable()) .subscribe()
41. interface ScopeProvider { fun requestScope(): Maybe<*> }
42. interface LifecycleScopeProvider<E> { fun correspondingEvents(): Function<E, E> fun peekLifecycle(): E fun lifecycle(): Observable<E> }
43. interface ScopeProvider { fun requestScope(): Maybe<*> }
44. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose .with(this) // ScopeProvider .forObservable()) .subscribe()
45. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .subscribe()
46. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .subscribe() .disposeOn(lifecycle)
47. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .subscribe { // Stuff } .disposeOn(lifecycle)
48. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .subscribe { // Stuff // Stuff // Stuff // Stuff // Stuff // Stuff }
49. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .subscribe { // Stuff // Stuff // Stuff // Stuff // Stuff // Stuff } .disposeOn(lifecycle)
50. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .subscribe({ r -> // Handle response }) { error: Throwable -> // Stuff // Stuff } .disposeOn(lifecycle)
51. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .delaySubscription(attaches()) .subscribe() .disposeOn(lifecycle)
52. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .delaySubscription(attaches()) .subscribe(myObserver) .disposeOn(lifecycle)
53. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .delaySubscription(attaches()) .subscribe(myObserver) .disposeOn(lifecycle)
54. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .subscribe()
55. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .subscribe(BoundObservers.<Response>forObservable(lifecycle) .onNext(...) .create())
56. .subscribe(BoundObservers.<Response>forObservable(lifecycle) .onNext(...) .create())
57. .subscribe(BoundObservers.<Response>forObservable(lifecycle) .onNext(...) .create())
58. .subscribe(BoundObservers.<Response>forObservable(lifecycle) .onNext(...) .create())
59. .subscribe(BoundObservers.<Response>forObservable(lifecycle) .onNext(...) .create())
60. .subscribe(BoundObservers.<Response>forObservable(lifecycle) .onNext(...) .onError(...) .create())
61. .subscribe(BoundObservers.<Response>forObservable(lifecycle) .onNext(...) .create())
62. .subscribe(BoundObservers.<Response>forObservable(lifecycle) .onNext(...) .create())
63. .subscribe(BoundObservers.<Response>forObservable(lifecycle) .onNext(...) .onError(...) .create())
64. .subscribe(BoundObservers.<Response>forObservable(lifecycle) .onNext(...) .onError(...) .onComplete(...) .create())
65. .subscribe()
66. .subscribe(BoundObservers.<Response>forObservable(lifecycle) .create())
67. .subscribe(BoundObservers.<Response>forObservable(lifecycle) .create())
68. .subscribe(BoundObservers.forObservable(lifecycle) .create())
69. .subscribe(BoundObservers.forObservable(lifecycle) .onNext(Object o -> ???) // ಠ_ಠ .create())
70. .subscribe(BoundObservers.<Response>forObservable(lifecycle) .onNext(Object o -> ???) // ಠ_ಠ .create())
71. .subscribe(BoundObservers.<Response>forObservable(lifecycle) .onNext(Response r -> ...) // :D .create())
72. .subscribe(BoundObservers.<Response>forObservable(lifecycle) .create())
73. ResponseObserver o = ResponseObserver() .subscribe(BoundObservers.<Response>forObservable(lifecycle) .create())
74. class ResponseObserver : BoundObserver<Response>() { // :( }
75. ResponseObserver o = ResponseObserver() .subscribe(BoundObservers.<Response>forObservable(lifecycle) .create())
76. ResponseObserver o = ResponseObserver() PublishSubject<Response> sub = PublishSubject.create() .subscribe(BoundObservers.<Response>forObservable(lifecycle) .create())
77. PublishSubject<Response> sub = PublishSubject.create() .subscribe(BoundObservers.<Response>forObservable(lifecycle) .create())
78. PublishSubject<Response> sub = PublishSubject.create() .subscribe(BoundObservers.<Response>forObservable(lifecycle) .around(sub))
79. PublishSubject<Response> sub = PublishSubject.create() .subscribe(BoundObservers.<Response>forObservable(lifecycle) .around(sub))
80. PublishSubject<Response> sub = PublishSubject.create() .subscribe(BoundObservers.<Response>forObservable(lifecycle) .onNext(...) .around(sub))
81. PublishSubject<Response> sub = PublishSubject.create() .subscribe(BoundObservers.<Response>forObservable(lifecycle) .onNext(...) .around(sub))
82. PublishSubject<Response> sub = PublishSubject.create() .subscribe(BoundObservers.<Response>forObservable(lifecycle) .onNext(...) .onNext(...) .onNext(...) .onNext(...) .onNext(...) .onNext(...) .onNext(...) .around(sub))
83. .subscribe(BoundObservers.<Response>forObservable(lifecycle) .create())
84. .subscribe(AutoDispose.<Response>forObservable(lifecycle) .create())
85. .subscribe(AutoDispose.<Response>forObservable(lifecycle) .around(...))
86. fun around(o: Observer<T>) fun around(c: Consumer<T>) fun around(c: Consumer<T>, e: Consumer<Throwable>) fun around(c: Consumer<T>, e: Consumer<Throwable>, a: Action) // Etc
87. fun around(o: Observer<T>) fun around(c: Consumer<T>) fun around(c: Consumer<T>, e: Consumer<Throwable>) fun around(c: Consumer<T>, e: Consumer<Throwable>, a: Action) fun empty() // Etc
88. interface AroundClause<T> { fun around(o: Observer<T>) fun around(c: Consumer<T>) fun around(c: Consumer<T>, e: Consumer<Throwable>) fun around(c: Consumer<T>, e: Consumer<Throwable>, a: Action) fun empty() // Etc }
89. ResponseObserver o = new ResponseObserver() .subscribe(AutoDispose.<Response>forObservable(lifecycle) .around(o)) V2 : AroundClause
90. ResponseObserver o = new ResponseObserver() .subscribe(AutoDispose.<Response>forObservable(lifecycle) .around(o))
91. ResponseObserver o = new ResponseObserver() .subscribe(AutoDispose.<Response>observable() .scopeWith(lifecycle) .around(o)) V3
92. ResponseObserver o = new ResponseObserver() .subscribe(AutoDispose.<Response>observable() .scopeWith(scope) .around(o)) V3
93. ResponseObserver o = new ResponseObserver() .subscribe(AutoDispose.<Response>observable() .scopeWith(scope) .around(o))
94. ResponseObserver o = new ResponseObserver() .subscribe(AutoDispose.<Response>observable() .scopeWith(scope) .around(o))
95. ResponseObserver o = new ResponseObserver() .subscribe(AutoDispose.<Response>observable() .scopeWith(scope) .around(o))
96. ResponseObserver o = new ResponseObserver() .subscribe(AutoDispose.<Response>observable() .scopeWith(scope) .around(o))
97. interface AroundClause<T> { fun around(o: Observer<T>) fun around(c: Consumer<T>) fun around(c: Consumer<T>, e: Consumer<Throwable>) fun around(c: Consumer<T>, e: Consumer<Throwable>, a: Action) fun empty() // Etc }
98. interface AroundClause { fun <T> around(o: Observer<T>) fun <T> around(c: Consumer<T>) fun <T> around(c: Consumer<T>, e: Consumer<Throwable>) fun <T> around(c: Consumer<T>, e: Consumer<Throwable>, a: Action) fun empty() // Etc }
99. ResponseObserver o = new ResponseObserver() .subscribe(AutoDispose.<Response>observable() .scopeWith(scope) .around(o))
100. ResponseObserver o = new ResponseObserver() .subscribe(AutoDispose.observable() .scopeWith(scope) .around(o))
101. ResponseObserver o = new ResponseObserver() .subscribe(AutoDispose.observable() .scopeWith(scope) .around(new Consumer<Response>() { // Impl }))
102. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .subscribe(AutoDispose.observable() .scopeWith(scope) .around(new Consumer<Response>() { // Impl })) V4
103. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .subscribe(AutoDispose.observable() .scopeWith(scope) .around(new Consumer<Response>() { // Impl }))
104. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .subscribe(AutoDispose.observable() .scopeWith(scope) .around(new Consumer<Response>() { @Override public void accept(Response r) { handleResponse(r) } }))
105. .to()
106. .to(new Function<Observable<T>, ???>() {})
107. .to(new Function<Observable<T>, AroundClause>() {})
108. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .subscribe(AutoDispose.observable() .scopeWith(scope) .around(new Consumer<Response>() { @Override public void accept(Response r) { handleResponse(r) }x }))
109. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(???) .subscribe(AutoDispose.observable() .scopeWith(scope) .around(new Consumer<Response>() { @Override public void accept(Response r) { handleResponse(r) }x }))
110. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(???) .around(new Consumer<Response>() { @Override public void accept(Response r) { handleResponse(r) }x }))
111. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose.observable() .scopeWith(scope)) .around(new Consumer<Response>() { @Override public void accept(Response r) { handleResponse(r) }x }))
112. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose.observable() .scopeWith(scope)) .around(new Consumer<Object>() { @Override public void accept(Object r) { handleResponse(r) }x }))
113. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose.observable() .scopeWith(scope)) .around(new Consumer<Object>() { @Override public void accept(Object r) { // (╯°□°）╯︵ ┻━┻ }x }))
114. class ObservableScoper<T> implements Function<Observable<T>, AroundClause> { }v
115. class ObservableScoper<T> implements Function<Observable<T>, AroundClause> { ObservableScoper(Maybe<?> scope) { // ... }a }v
116. class ObservableScoper<T> implements Function<Observable<T>, AroundClause> { ObservableScoper(Maybe<?> scope) { // ... }a @Override public AroundClause apply(Observable<T> o) { }b }v
117. class ObservableScoper<T> implements Function<Observable<T>, AroundClause> { ObservableScoper(Maybe<?> scope) { // ... }a @Override public AroundClause apply(Observable<T> o) { return new AroundClause() { // ... }c }b }v
118. class ObservableScoper<T> implements Function<Observable<T>, AroundClause<T>> { ObservableScoper(Maybe<?> scope) { // ... }a @Override public AroundClause<T> apply(Observable<T> o) { return new AroundClause<T>() { // ... }c }b }v
119. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(new ObservableScoper<Response>(scope)) .around(new Consumer<Response>() { @Override public void accept(Response r) { handleResponse(r) } }))
120. interface AroundClause<T> { fun around(o: Observer<T>) fun around(c: Consumer<T>) fun around(c: Consumer<T>, e: Consumer<Throwable>) fun around(c: Consumer<T>, e: Consumer<Throwable>, a: Action) fun empty() // Etc }
121. interface SubscribeProxy<T> { fun around(o: Observer<T>) fun around(c: Consumer<T>) fun around(c: Consumer<T>, e: Consumer<Throwable>) fun around(c: Consumer<T>, e: Consumer<Throwable>, a: Action) fun empty() // Etc }
122. interface SubscribeProxy<T> { fun subscribe(o: Observer<T>) fun subscribe(c: Consumer<T>) fun subscribe(c: Consumer<T>, e: Consumer<Throwable>) fun subscribe(c: Consumer<T>, e: Consumer<Throwable>, a: Action) fun empty() // Etc }
123. interface SubscribeProxy<T> { fun subscribe(o: Observer<T>) fun subscribe(c: Consumer<T>) fun subscribe(c: Consumer<T>, e: Consumer<Throwable>) fun subscribe(c: Consumer<T>, e: Consumer<Throwable>, a: Action) fun subscribe() // Etc }
124. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(new ObservableScoper<Response>(scope)) .around(new Consumer<Response>() { @Override public void accept(Response r) { handleResponse(r) } }))
125. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(new ObservableScoper<Response>(scope)) .subscribe(new Consumer<Response>() { @Override public void accept(Response r) { handleResponse(r) } }))
126. –Nick Butcher, and probably other people “If it looks right, it is right.”
127. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(new ObservableScoper<Response>(scope)) .subscribe(newxConsumer<Response>() { @Override public void accept(Response r) { handleResponse(r) }x })) V5
128. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose.with(scope).<Response>forObservable()) .subscribe(newxConsumer<Response>() { @Override public void accept(Response r) { handleResponse(r) }x }))
129. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose.with(scope).forObservable()) .subscribe(new Consumer<Response>() { @Override public void accept(Response r) { handleResponse(r) }x }))
130. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose.forObservable(scope)) .subscribe(new Consumer<Response>() { @Override public void accept(Response r) { handleResponse(r) }x }))
132. https://youtrack.jetbrains.com/issue/ IDEA-179864
133. apiRequest() .subscribeOn(io()) .observeOn(mainThread()) .to(AutoDispose.forObservable(scope)) .subscribe(new Consumer<Response>() { @Override public void accept(Response r) { handleResponse(r) }x }))
134. aWhat makes ana API good? !
135. “Prefer exposing interfaces”
136. “Prefer exposing interfaces” interface SubscribeProxy<T> { fun subscribe(o: Observer<T>) fun subscribe(c: Consumer<T>) fun subscribe(c: Consumer<T>, e: Consumer<Throwable>) fun subscribe(c: Consumer<T>, e: Consumer<Throwable>, a: Action) fun subscribe() // Etc }
137. “Prefer composition in accepting external implementations. Inheritance can be inconvenient.”
138. “Prefer composition in accepting external implementations. Inheritance can be inconvenient.” class ResponseObserver : BoundObserver<Response>() { // :( } PublishSubject<Response> sub = PublishSubject.create()
139. “Prefer final by default”
140. “Identify footguns”
141. “Identify footguns” .subscribe(BoundObservers.<Response>forObservable(lifecycle) .onNext(...) .onNext(...) .onNext(...) .onNext(...) .onNext(...) .onNext(...) .onNext(...) .around(sub))
142. “Dependency on lint should be avoided”
143. “Dependency on lint should be avoided”
144. “IDE experience matters”
145. “IDE experience matters” .around(new Consumer<Object>() { @Override public void accept(Object r) { // (╯°□°）╯︵ ┻━┻ }x }))
146. “Crack eggs, make omelettes” V4 V5 V0 V3 V1
148. Questions? Zac Sweers - Uber @pandanomic