Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Beyond REST: Web Services Designed for Mobile

Beyond REST: Web Services Designed for Mobile

Creating the best possible mobile experience extends beyond the device to the services your app depends on. The unique constraints imposed by mobile devices should influence your API design. Learn how to build great mobile web services, what REST doesn't cover, and lessons from years of experience designing and refining mobile web services.

Sam Kirchmeier

April 11, 2015
Tweet

More Decks by Sam Kirchmeier

Other Decks in Programming

Transcript

  1. BEYOND REST
    WEB SERVICES
    DESIGNED
    FOR MOBILE

    View full-size slide

  2. tchacknight.com

    View full-size slide

  3. Web Services
    Native Apps

    View full-size slide

  4. Web Services
    Native Apps
    People

    View full-size slide

  5. Web API state of the art
    TOPICS

    View full-size slide

  6. Web API state of the art
    Design considerations for developers
    TOPICS

    View full-size slide

  7. Web API state of the art
    Design considerations for developers
    Lessons and patterns
    TOPICS

    View full-size slide

  8. STATE OF THE ART

    View full-size slide

  9. WHY REVIEW REST?

    View full-size slide

  10. WHY REVIEW REST?
    Defines our constraints
    It might not be what you think it is
    It’s really cool

    View full-size slide

  11. REST
    Representational State Transfer

    View full-size slide

  12. REST
    Representational State Transfer
    Coined by Roy Fielding in 2000

    View full-size slide

  13. REST
    Representational State Transfer
    Coined by Roy Fielding in 2000
    The architectural style of the web

    View full-size slide

  14. REST
    Representational State Transfer
    Coined by Roy Fielding in 2000
    The architectural style of the web
    Deduced from and tested by the web itself

    View full-size slide

  15. “[REST] has allowed
    Web-based applications
    to scale from 100,000
    requests per day in 1994
    to 600,000,000 requests
    per day in 1999.”
    –Roy Fielding
    Source: https://www.ics.uci.edu/~fielding/pubs/dissertation/conclusions.htm

    View full-size slide

  16. 0
    2,250,000,000
    4,500,000,000
    6,750,000,000
    9,000,000,000
    1999 (Everything) 2015 (Just YouTube)
    REQUESTS PER DAY
    Source: http://www.internetlivestats.com/one-second/#youtube-band

    View full-size slide

  17. QUALITIES OF THE WEB
    Simple
    Proven
    Scalable
    Ubiquitous

    View full-size slide

  18. QUALITIES OF THE WEB
    Simple
    Proven
    Scalable
    Ubiquitous
    So aren’t all web APIs REST?

    View full-size slide

  19. “What needs to be done to make the
    REST architectural style clear on the
    notion that hypertext is a constraint? In
    other words, if the engine of application
    state (and hence the API) is not being
    driven by hypertext, then it cannot be
    RESTful and cannot be a REST API.
    Period. Is there some broken manual
    somewhere that needs to be fixed?”
    –Roy Fielding, 2008
    Source: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

    View full-size slide

  20. HATEOAS
    Client doesn’t need a manual

    View full-size slide

  21. HATEOAS
    Client doesn’t need a manual
    Client doesn’t know URL formats

    View full-size slide

  22. HATEOAS
    Client doesn’t need a manual
    Client doesn’t know URL formats
    Client doesn’t know available states

    View full-size slide

  23. HATEOAS
    Client doesn’t need a manual
    Client doesn’t know URL formats
    Client doesn’t know available states
    Works for more than just read-only data

    View full-size slide

  24. GET /sign_up

    View full-size slide

  25. GET /sign_up
    HTML

    View full-size slide

  26. GET /sign_up
    HTML
    POST /sign_up

    View full-size slide

  27. GET /sign_up
    HTML
    POST /sign_up
    200 OK

    View full-size slide

  28. GET /sign_up
    HTML
    1 2

    View full-size slide

  29. GET /sign_up
    HTML
    POST /sign_up
    200 OK
    1 2

    View full-size slide

  30. GET /sign_up
    HTML
    1 2

    View full-size slide

  31. GET /sign_up
    HTML
    POST /sign_up
    Error
    E
    1 2

    View full-size slide

  32. GET /sign_up
    HTML
    POST /sign_up
    200 OK
    C C
    1 2

    View full-size slide

  33. POST /sign_up
    200 OK
    C
    C

    View full-size slide

  34. POST /sign_up
    200 OK
    C
    C
    GET /sign_up
    { sign_up }

    View full-size slide

  35. “There is so much
    coupling on display
    that it should be given
    an X rating.”
    –Roy Fielding
    Source: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

    View full-size slide

  36. POST /sign_up
    200 OK
    C
    C
    GET /sign_up
    { sign_up }

    View full-size slide

  37. C
    C
    { sign_up }

    View full-size slide

  38. HATEOAS
    Use a native wrapper like PhoneGap?

    View full-size slide

  39. HATEOAS
    Use a native wrapper like PhoneGap?
    Use React Native?

    View full-size slide

  40. HATEOAS
    Use a native wrapper like PhoneGap?
    Use React Native?
    Something else?

    View full-size slide

  41. HATEOAS
    Use a native wrapper like PhoneGap?
    Use React Native?
    Something else?
    Compensate

    View full-size slide

  42. “REST isn’t an all or
    nothing proposition.
    One can get significant
    value from partial
    adoption.”
    –Sam Ruby
    Source: http://www.intertwingly.net/blog/2008/10/21/Progressive-Disclosure

    View full-size slide

  43. CONSIDERATIONS
    FOR DEVELOPERS

    View full-size slide

  44. FOR DEVELOPERS

    View full-size slide

  45. FOR DEVELOPERS
    Documented

    View full-size slide

  46. FOR DEVELOPERS
    Documented
    Consistent

    View full-size slide

  47. FOR DEVELOPERS
    Documented
    Consistent
    Testable

    View full-size slide

  48. COUPLING &
    PERMANENCE
    C

    View full-size slide

  49. DOCUMENTATION
    FOR DEVELOPERS

    View full-size slide

  50. FOR DEVELOPERS
    DOCUMENTATION
    Treat it like any other feature

    View full-size slide

  51. FOR DEVELOPERS
    DOCUMENTATION
    Treat it like any other feature
    Must be up-to-date

    View full-size slide

  52. FOR DEVELOPERS
    DOCUMENTATION
    Treat it like any other feature
    Must be up-to-date
    Good: Auto-validate

    View full-size slide

  53. FOR DEVELOPERS
    DOCUMENTATION
    Treat it like any other feature
    Must be up-to-date
    Good: Auto-validate
    Better: Auto-generate

    View full-size slide

  54. FOR DEVELOPERS
    DOCUMENTATION
    Treat it like any other feature
    Must be up-to-date
    Good: Auto-validate
    Better: Auto-generate
    Critical for developer happiness

    View full-size slide

  55. FOR DEVELOPERS
    DOCUMENTATION
    Reference
    Troubleshooting
    Change

    View full-size slide

  56. FOR DEVELOPERS
    DOCUMENTATION
    Reference Docs
    Authentication
    Version Details
    Request Headers
    Response Headers
    Response Format
    Status Codes
    Backwards Compatibility
    Pagination
    Resources
    Methods
    Method Parameters
    Example Requests
    Example Responses
    Error Format

    View full-size slide

  57. FOR DEVELOPERS
    DOCUMENTATION
    Reference Docs Examples
    https://stripe.com/docs/api
    https://instagram.com/developer
    https://developer.github.com/v3

    View full-size slide

  58. FOR DEVELOPERS
    DOCUMENTATION
    Troubleshooting

    View full-size slide

  59. FOR DEVELOPERS
    DOCUMENTATION
    Troubleshooting
    Minimum: Detailed error messages
    Better: Errors with links to reference docs

    View full-size slide

  60. FOR DEVELOPERS
    DOCUMENTATION
    Document Change

    View full-size slide

  61. FOR DEVELOPERS
    DOCUMENTATION
    Document Change
    Minimum: Changelog
    Better: Mailing list

    View full-size slide

  62. CONSISTENCY
    FOR DEVELOPERS

    View full-size slide

  63. FOR DEVELOPERS
    CONSISTENCY
    Don’t deviate from the norm

    View full-size slide

  64. FOR DEVELOPERS
    CONSISTENCY
    Don’t deviate from the norm
    Use standard HTTP verbs
    GET Get a resource
    POST Create a resource
    PUT Replace a resource
    PATCH Update a resource
    DELETE Delete a resource

    View full-size slide

  65. FOR DEVELOPERS
    CONSISTENCY
    Provide consistent error responses

    View full-size slide

  66. POST /sign_up

    View full-size slide

  67. POST /sign_up
    E

    View full-size slide

  68. POST /sign_up
    200 OK
    E

    View full-size slide

  69. POST /sign_up
    200 OK
    E

    View full-size slide

  70. POST /sign_up
    200 OK
    POST /sign_up
    200 OK
    E
    E

    View full-size slide

  71. POST /sign_up
    200 OK
    POST /sign_up
    200 OK
    E
    E
    X

    View full-size slide

  72. POST /sign_up
    200 OK
    POST /sign_up
    422 Invalid
    E
    E

    View full-size slide

  73. FOR DEVELOPERS
    CONSISTENCY
    Use standard HTTP status codes
    200 Success
    201 Created
    400 Bad request
    401 Unauthorized
    404 Not found
    422 Unprocessable entity
    500 Server error

    View full-size slide

  74. FOR DEVELOPERS
    CONSISTENCY
    Backwards compatibility

    View full-size slide

  75. FOR DEVELOPERS
    CONSISTENCY
    Backwards compatibility
    Publish your contract

    View full-size slide

  76. FOR DEVELOPERS
    CONSISTENCY
    Backwards compatibility
    Publish your contract
    Adding new stuff is OK

    View full-size slide

  77. FOR DEVELOPERS
    CONSISTENCY
    Backwards compatibility
    Publish your contract
    Adding new stuff is OK
    Removing stuff is not OK :(

    View full-size slide

  78. FOR DEVELOPERS
    CONSISTENCY
    Backwards compatibility
    Publish your contract
    Adding new stuff is OK
    Removing stuff is not OK :(
    Making a backwards-incompatible change
    creates a new version of the API

    View full-size slide

  79. FOR DEVELOPERS
    CONSISTENCY
    How Stripe handles versions

    View full-size slide

  80. FOR DEVELOPERS
    CONSISTENCY
    How Stripe handles versions
    Backwards compatibility is “hidden”

    View full-size slide

  81. FOR DEVELOPERS
    CONSISTENCY
    How Stripe handles versions
    Backwards compatibility is “hidden”
    New users are on the latest version

    View full-size slide

  82. FOR DEVELOPERS
    CONSISTENCY
    How Stripe handles versions
    Backwards compatibility is “hidden”
    New users are on the latest version
    Stripe adds breaking changes with gates

    View full-size slide

  83. FOR DEVELOPERS
    CONSISTENCY
    How Stripe handles versions
    Backwards compatibility is “hidden”
    New users are on the latest version
    Stripe adds breaking changes with gates
    Users can update to the latest anytime

    View full-size slide

  84. TESTABLE
    FOR DEVELOPERS

    View full-size slide

  85. FOR DEVELOPERS
    TESTABLE
    Web APIs must be testable

    View full-size slide

  86. FOR DEVELOPERS
    TESTABLE
    Web APIs must be testable
    Minimum: Staging, Sandbox, or Test Mode
    Better: Developers run a local server

    View full-size slide

  87. LESSONS &
    PATTERNS

    View full-size slide

  88. PATTERNS
    Kill switch

    View full-size slide

  89. PATTERNS
    Kill switch
    Source of truth

    View full-size slide

  90. PATTERNS
    Kill switch
    Source of truth
    Pubsub

    View full-size slide

  91. KILL SWITCH
    PATTERNS

    View full-size slide

  92. Can I have my
    data, please?
    You need to
    upgrade, sorry!
    :(

    View full-size slide

  93. PATTERNS
    KILL SWITCH
    A must have

    View full-size slide

  94. PATTERNS
    KILL SWITCH
    A must have
    Minimum: Force an upgrade

    View full-size slide

  95. PATTERNS
    KILL SWITCH
    A must have
    Minimum: Force an upgrade
    Better: Communicate with users

    View full-size slide

  96. PATTERNS
    KILL SWITCH
    Hypothetical situation

    View full-size slide

  97. PATTERNS
    KILL SWITCH
    Hypothetical situation
    You have an app in the App Store

    View full-size slide

  98. PATTERNS
    KILL SWITCH
    Hypothetical situation
    You have an app in the App Store
    You discover a bug and start fixing it

    View full-size slide

  99. PATTERNS
    KILL SWITCH
    Hypothetical situation
    You have an app in the App Store
    You discover a bug and start fixing it
    Meanwhile, end users also discover it

    View full-size slide

  100. PATTERNS
    KILL SWITCH
    Hypothetical situation
    You have an app in the App Store
    You discover a bug and start fixing it
    Meanwhile, end users also discover it
    You’re helpless for 1 or 2 weeks

    View full-size slide

  101. PATTERNS
    KILL SWITCH
    Hypothetical situation
    You have an app in the App Store
    You discover a bug and start fixing it
    Meanwhile, end users also discover it
    You’re helpless for 1 or 2 weeks
    Alert them

    View full-size slide

  102. App version
    Platform
    OS version
    Device
    User-Agent MyApp/3.07.01 (Android; 5.0.2; Galaxy S6)
    KILL SWITCH PATTERNS

    View full-size slide

  103. SOURCE OF TRUTH
    PATTERNS

    View full-size slide

  104. PATTERNS
    SOURCE OF TRUTH
    The server is always the source of truth

    View full-size slide

  105. PATTERNS
    SOURCE OF TRUTH
    The server is always the source of truth
    Except when it isn’t

    View full-size slide

  106. PATTERNS
    SOURCE OF TRUTH
    The server is always the source of truth
    Except when it isn’t
    What about when resources are created?

    View full-size slide

  107. PATTERNS
    SOURCE OF TRUTH
    The server is always the source of truth
    Except when it isn’t
    What about when resources are created?
    What about airplane mode?

    View full-size slide

  108. PATTERNS
    SOURCE OF TRUTH
    Keep it simple

    View full-size slide

  109. PATTERNS
    SOURCE OF TRUTH
    Keep it simple
    Minimize client state

    View full-size slide

  110. PATTERNS
    SOURCE OF TRUTH
    Keep it simple
    Minimize client state
    Sync is an interesting, hard problem

    View full-size slide

  111. PUBSUB
    PATTERNS

    View full-size slide

  112. PATTERNS
    PUBSUB
    Publishers
    Channels
    Subscribers

    View full-size slide

  113. PATTERNS
    PUBSUB
    Publishers
    Channels
    Subscribers
    Publishers and subscribers don’t know
    about each other

    View full-size slide

  114. GET /stream
    200 OK

    View full-size slide

  115. POST /like
    201 Created

    View full-size slide

  116. POST /like
    201 Created

    View full-size slide

  117. POST /like
    201 Created

    View full-size slide

  118. POST /like
    201 Created

    View full-size slide

  119. Channel Subscriber
    1

    View full-size slide

  120. POST /like
    Channel Subscriber
    1
    Update!
    Update!

    View full-size slide

  121. POST /like
    Channel Subscriber
    1
    Update!
    Update!
    Subscriber
    2
    Update!
    Subscrib
    3
    Update!

    View full-size slide

  122. Channel Subscriber
    1
    Update!
    Subscriber
    2
    Update!
    Subscrib
    3
    Update!
    POST /like
    Update!

    View full-size slide

  123. GET /stream
    200 OK
    Pushpin

    View full-size slide

  124. Pushpin
    GET /stream

    View full-size slide

  125. Pushpin
    GET /stream
    GET /stream

    View full-size slide

  126. Pushpin
    GET /stream
    GET /stream
    Open #channel

    View full-size slide

  127. Pushpin
    GET /stream
    200 OK chunked
    GET /stream
    Open #channel

    View full-size slide

  128. Pushpin
    GET /stream
    200 OK chunked
    GET /stream
    Open #channel
    POST /like

    View full-size slide

  129. Pushpin
    GET /stream
    200 OK chunked
    GET /stream
    Open #channel
    Publish #channel
    POST /like

    View full-size slide

  130. Pushpin
    GET /stream
    200 OK chunked
    GET /stream
    Open #channel
    Publish #channel
    Publish #channel
    Publish #channel
    POST /like
    POST /like
    POST /like

    View full-size slide

  131. Pushpin
    GET /stream
    200 OK chunked
    GET /stream
    Open #channel
    Publish #channel
    Publish #channel
    Publish #channel
    POST /like
    POST /like
    POST /like

    View full-size slide

  132. Pushpin
    GET /stream
    200 OK chunked
    GET /stream
    Open #channel
    Publish #channel
    Publish #channel
    Publish #channel
    POST /like
    POST /like
    POST /like

    View full-size slide

  133. PUSHPIN
    Transparent infrastructure layer

    View full-size slide

  134. PUSHPIN
    Transparent infrastructure layer
    Independently scalable

    View full-size slide

  135. PUSHPIN
    Transparent infrastructure layer
    Independently scalable
    Simple for clients

    View full-size slide

  136. PUSHPIN
    Transparent infrastructure layer
    Independently scalable
    Simple for clients
    Open source

    View full-size slide

  137. Shared some tips and lessons learned
    Importance of developer experience
    Web API state of the art
    RECAP

    View full-size slide

  138. https://github.com/livefront/beyond-rest
    Sam Kirchmeier
    @skirchmeier
    THANKS!

    View full-size slide