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.

E5703b43507ace0a59aaa59e053d3e61?s=128

Sam Kirchmeier

April 11, 2015
Tweet

Transcript

  1. BEYOND REST WEB SERVICES DESIGNED FOR MOBILE

  2. None
  3. tchacknight.com

  4. Web Services Native Apps

  5. Web Services Native Apps People

  6. TOPICS

  7. Web API state of the art TOPICS

  8. Web API state of the art Design considerations for developers

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

    Lessons and patterns TOPICS
  10. STATE OF THE ART

  11. WHY REVIEW REST?

  12. WHY REVIEW REST? Defines our constraints It might not be

    what you think it is It’s really cool
  13. REST

  14. REST Representational State Transfer

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

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

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

    The architectural style of the web Deduced from and tested by the web itself
  18. “[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
  19. 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
  20. QUALITIES OF THE WEB Simple Proven Scalable Ubiquitous

  21. QUALITIES OF THE WEB Simple Proven Scalable Ubiquitous So aren’t

    all web APIs REST?
  22. “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
  23. HATEOAS

  24. nytimes.com

  25. nytimes.com

  26. HATEOAS

  27. HATEOAS Client doesn’t need a manual

  28. HATEOAS Client doesn’t need a manual Client doesn’t know URL

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

    formats Client doesn’t know available states
  30. 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
  31. None
  32. GET /sign_up

  33. GET /sign_up HTML <form>

  34. GET /sign_up HTML <form> POST /sign_up

  35. GET /sign_up HTML <form> POST /sign_up 200 OK

  36. 1 2

  37. GET /sign_up HTML <form> 1 2

  38. GET /sign_up HTML <form> POST /sign_up 200 OK 1 2

  39. GET /sign_up HTML <form> 1 2

  40. GET /sign_up HTML <form> POST /sign_up Error E 1 2

  41. GET /sign_up HTML <form> POST /sign_up 200 OK C C

    1 2
  42. POST /sign_up 200 OK C C

  43. POST /sign_up 200 OK C C GET /sign_up { sign_up

    }
  44. “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
  45. POST /sign_up 200 OK C C GET /sign_up { sign_up

    }
  46. C C { sign_up }

  47. HATEOAS Use a native wrapper like PhoneGap?

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

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

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

    Something else? Compensate
  51. “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
  52. CONSIDERATIONS FOR DEVELOPERS

  53. FOR DEVELOPERS

  54. FOR DEVELOPERS Documented

  55. FOR DEVELOPERS Documented Consistent

  56. FOR DEVELOPERS Documented Consistent Testable

  57. COUPLING & PERMANENCE C

  58. DOCUMENTATION FOR DEVELOPERS

  59. FOR DEVELOPERS DOCUMENTATION Treat it like any other feature

  60. FOR DEVELOPERS DOCUMENTATION Treat it like any other feature Must

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

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

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

    be up-to-date Good: Auto-validate Better: Auto-generate Critical for developer happiness
  64. FOR DEVELOPERS DOCUMENTATION Reference Troubleshooting Change

  65. 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
  66. FOR DEVELOPERS DOCUMENTATION Reference Docs Examples https://stripe.com/docs/api https://instagram.com/developer https://developer.github.com/v3

  67. FOR DEVELOPERS DOCUMENTATION Troubleshooting

  68. FOR DEVELOPERS DOCUMENTATION Troubleshooting Minimum: Detailed error messages Better: Errors

    with links to reference docs
  69. FOR DEVELOPERS DOCUMENTATION Document Change

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

  71. CONSISTENCY FOR DEVELOPERS

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

  73. 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
  74. FOR DEVELOPERS CONSISTENCY Provide consistent error responses

  75. POST /sign_up

  76. POST /sign_up E

  77. POST /sign_up 200 OK E

  78. POST /sign_up 200 OK E

  79. POST /sign_up 200 OK POST /sign_up 200 OK E E

  80. POST /sign_up 200 OK POST /sign_up 200 OK E E

    X
  81. POST /sign_up 200 OK POST /sign_up 422 Invalid E E

  82. 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
  83. FOR DEVELOPERS CONSISTENCY Backwards compatibility

  84. FOR DEVELOPERS CONSISTENCY Backwards compatibility Publish your contract

  85. FOR DEVELOPERS CONSISTENCY Backwards compatibility Publish your contract Adding new

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

    stuff is OK Removing stuff is not OK :(
  87. 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
  88. FOR DEVELOPERS CONSISTENCY How Stripe handles versions

  89. FOR DEVELOPERS CONSISTENCY How Stripe handles versions Backwards compatibility is

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

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

    “hidden” New users are on the latest version Stripe adds breaking changes with gates
  92. 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
  93. TESTABLE FOR DEVELOPERS

  94. FOR DEVELOPERS TESTABLE Web APIs must be testable

  95. FOR DEVELOPERS TESTABLE Web APIs must be testable Minimum: Staging,

    Sandbox, or Test Mode Better: Developers run a local server
  96. LESSONS & PATTERNS

  97. PATTERNS Kill switch

  98. PATTERNS Kill switch Source of truth

  99. PATTERNS Kill switch Source of truth Pubsub

  100. KILL SWITCH PATTERNS

  101. Can I have my data, please? You need to upgrade,

    sorry! :(
  102. PATTERNS KILL SWITCH A must have

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

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

    Better: Communicate with users
  105. PATTERNS KILL SWITCH Hypothetical situation

  106. PATTERNS KILL SWITCH Hypothetical situation You have an app in

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

    the App Store You discover a bug and start fixing it
  108. 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
  109. 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
  110. 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
  111. App version Platform OS version Device User-Agent MyApp/3.07.01 (Android; 5.0.2;

    Galaxy S6) KILL SWITCH PATTERNS
  112. SOURCE OF TRUTH PATTERNS

  113. PATTERNS SOURCE OF TRUTH The server is always the source

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

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

    of truth Except when it isn’t What about when resources are created?
  116. 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?
  117. None
  118. None
  119. PATTERNS SOURCE OF TRUTH Keep it simple

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

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

    Sync is an interesting, hard problem
  122. PUBSUB PATTERNS

  123. PATTERNS PUBSUB Publishers Channels Subscribers

  124. PATTERNS PUBSUB Publishers Channels Subscribers Publishers and subscribers don’t know

    about each other
  125. None
  126. None
  127. GET /stream

  128. GET /stream 200 OK

  129. None
  130. POST /like 201 Created

  131. POST /like 201 Created

  132. POST /like 201 Created

  133. POST /like 201 Created

  134. Channel Subscriber 1

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

  136. POST /like Channel Subscriber 1 Update! Update! Subscriber 2 Update!

    Subscrib 3 Update!
  137. Channel Subscriber 1 Update! Subscriber 2 Update! Subscrib 3 Update!

    POST /like Update!
  138. GET /stream 200 OK Pushpin

  139. Pushpin

  140. Pushpin GET /stream

  141. Pushpin GET /stream GET /stream

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

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

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

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

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

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

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

    Publish #channel Publish #channel Publish #channel POST /like POST /like POST /like
  149. PUSHPIN

  150. PUSHPIN Transparent infrastructure layer

  151. PUSHPIN Transparent infrastructure layer Independently scalable

  152. PUSHPIN Transparent infrastructure layer Independently scalable Simple for clients

  153. PUSHPIN Transparent infrastructure layer Independently scalable Simple for clients Open

    source
  154. RECAP

  155. Shared some tips and lessons learned Importance of developer experience

    Web API state of the art RECAP
  156. THANKS!

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