$30 off During Our Annual Pro Sale. View Details »

API Design as an Art

Zac Sweers
November 05, 2017

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.

Zac Sweers

November 05, 2017
Tweet

More Decks by Zac Sweers

Other Decks in Programming

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