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.

Transcript

1. BEYOND REST WEB SERVICES DESIGNED FOR MOBILE
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
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?
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
127. GET /stream
128. GET /stream 200 OK
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!