Beyond REST: Web Services Designed for Mobile

Slide 1

Slide 1 text

BEYOND REST WEB SERVICES DESIGNED FOR MOBILE

Slide 2

Slide 2 text

No content

Slide 3

Slide 3 text

tchacknight.com

Slide 4

Slide 4 text

Web Services Native Apps

Slide 5

Slide 5 text

Web Services Native Apps People

Slide 6

Slide 6 text

TOPICS

Slide 7

Slide 7 text

Web API state of the art TOPICS

Slide 8

Slide 8 text

Web API state of the art Design considerations for developers TOPICS

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

STATE OF THE ART

Slide 11

Slide 11 text

WHY REVIEW REST?

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

REST

Slide 14

Slide 14 text

REST Representational State Transfer

Slide 15

Slide 15 text

REST Representational State Transfer Coined by Roy Fielding in 2000

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

“[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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

QUALITIES OF THE WEB Simple Proven Scalable Ubiquitous

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

“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

Slide 23

Slide 23 text

HATEOAS

Slide 24

Slide 24 text

nytimes.com

Slide 25

Slide 25 text

nytimes.com

Slide 26

Slide 26 text

HATEOAS

Slide 27

Slide 27 text

HATEOAS Client doesn’t need a manual

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

No content

Slide 32

Slide 32 text

GET /sign_up

Slide 33

Slide 33 text

GET /sign_up HTML

Slide 34

Slide 34 text

GET /sign_up HTML POST /sign_up

Slide 35

Slide 35 text

GET /sign_up HTML POST /sign_up 200 OK

Slide 36

Slide 36 text

1 2

Slide 37

Slide 37 text

GET /sign_up HTML 1 2

Slide 38

Slide 38 text

GET /sign_up HTML POST /sign_up 200 OK 1 2

Slide 39

Slide 39 text

GET /sign_up HTML 1 2

Slide 40

Slide 40 text

GET /sign_up HTML POST /sign_up Error E 1 2

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

POST /sign_up 200 OK C C

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

“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

Slide 45

Slide 45 text

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

Slide 46

Slide 46 text

C C { sign_up }

Slide 47

Slide 47 text

HATEOAS Use a native wrapper like PhoneGap?

Slide 48

Slide 48 text

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

Slide 49

Slide 49 text

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

Slide 50

Slide 50 text

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

Slide 51

Slide 51 text

“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

Slide 52

Slide 52 text

CONSIDERATIONS FOR DEVELOPERS

Slide 53

Slide 53 text

FOR DEVELOPERS

Slide 54

Slide 54 text

FOR DEVELOPERS Documented

Slide 55

Slide 55 text

FOR DEVELOPERS Documented Consistent

Slide 56

Slide 56 text

FOR DEVELOPERS Documented Consistent Testable

Slide 57

Slide 57 text

COUPLING & PERMANENCE C

Slide 58

Slide 58 text

DOCUMENTATION FOR DEVELOPERS

Slide 59

Slide 59 text

FOR DEVELOPERS DOCUMENTATION Treat it like any other feature

Slide 60

Slide 60 text

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

Slide 61

Slide 61 text

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

Slide 62

Slide 62 text

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

Slide 63

Slide 63 text

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

Slide 64

Slide 64 text

FOR DEVELOPERS DOCUMENTATION Reference Troubleshooting Change

Slide 65

Slide 65 text

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

Slide 66

Slide 66 text

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

Slide 67

Slide 67 text

FOR DEVELOPERS DOCUMENTATION Troubleshooting

Slide 68

Slide 68 text

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

Slide 69

Slide 69 text

FOR DEVELOPERS DOCUMENTATION Document Change

Slide 70

Slide 70 text

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

Slide 71

Slide 71 text

CONSISTENCY FOR DEVELOPERS

Slide 72

Slide 72 text

FOR DEVELOPERS CONSISTENCY Don’t deviate from the norm

Slide 73

Slide 73 text

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

Slide 74

Slide 74 text

FOR DEVELOPERS CONSISTENCY Provide consistent error responses

Slide 75

Slide 75 text

POST /sign_up

Slide 76

Slide 76 text

POST /sign_up E

Slide 77

Slide 77 text

POST /sign_up 200 OK E

Slide 78

Slide 78 text

POST /sign_up 200 OK E

Slide 79

Slide 79 text

POST /sign_up 200 OK POST /sign_up 200 OK E E

Slide 80

Slide 80 text

POST /sign_up 200 OK POST /sign_up 200 OK E E X

Slide 81

Slide 81 text

POST /sign_up 200 OK POST /sign_up 422 Invalid E E ✓

Slide 82

Slide 82 text

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

Slide 83

Slide 83 text

FOR DEVELOPERS CONSISTENCY Backwards compatibility

Slide 84

Slide 84 text

FOR DEVELOPERS CONSISTENCY Backwards compatibility Publish your contract

Slide 85

Slide 85 text

FOR DEVELOPERS CONSISTENCY Backwards compatibility Publish your contract Adding new stuﬀ is OK

Slide 86

Slide 86 text

FOR DEVELOPERS CONSISTENCY Backwards compatibility Publish your contract Adding new stuﬀ is OK Removing stuﬀ is not OK :(

Slide 87

Slide 87 text

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

Slide 88

Slide 88 text

FOR DEVELOPERS CONSISTENCY How Stripe handles versions

Slide 89

Slide 89 text

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

Slide 90

Slide 90 text

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

Slide 91

Slide 91 text

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

Slide 92

Slide 92 text

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

Slide 93

Slide 93 text

TESTABLE FOR DEVELOPERS

Slide 94

Slide 94 text

FOR DEVELOPERS TESTABLE Web APIs must be testable

Slide 95

Slide 95 text

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

Slide 96

Slide 96 text

LESSONS & PATTERNS

Slide 97

Slide 97 text

PATTERNS Kill switch

Slide 98

Slide 98 text

PATTERNS Kill switch Source of truth

Slide 99

Slide 99 text

PATTERNS Kill switch Source of truth Pubsub

Slide 100

Slide 100 text

KILL SWITCH PATTERNS

Slide 101

Slide 101 text

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

Slide 102

Slide 102 text

PATTERNS KILL SWITCH A must have

Slide 103

Slide 103 text

PATTERNS KILL SWITCH A must have Minimum: Force an upgrade

Slide 104

Slide 104 text

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

Slide 105

Slide 105 text

PATTERNS KILL SWITCH Hypothetical situation

Slide 106

Slide 106 text

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

Slide 107

Slide 107 text

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

Slide 108

Slide 108 text

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

Slide 109

Slide 109 text

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

Slide 110

Slide 110 text

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

Slide 111

Slide 111 text

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

Slide 112

Slide 112 text

SOURCE OF TRUTH PATTERNS

Slide 113

Slide 113 text

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

Slide 114

Slide 114 text

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

Slide 115

Slide 115 text

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

Slide 116

Slide 116 text

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?

Slide 117

Slide 117 text

No content

Slide 118

Slide 118 text

No content

Slide 119

Slide 119 text

PATTERNS SOURCE OF TRUTH Keep it simple

Slide 120

Slide 120 text

PATTERNS SOURCE OF TRUTH Keep it simple Minimize client state

Slide 121

Slide 121 text

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

Slide 122

Slide 122 text

PUBSUB PATTERNS

Slide 123

Slide 123 text

PATTERNS PUBSUB Publishers Channels Subscribers

Slide 124

Slide 124 text

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

Slide 125

Slide 125 text

No content

Slide 126

Slide 126 text

No content

Slide 127

Slide 127 text

GET /stream

Slide 128

Slide 128 text

GET /stream 200 OK

Slide 129

Slide 129 text

No content

Slide 130

Slide 130 text

POST /like 201 Created

Slide 131

Slide 131 text

POST /like 201 Created

Slide 132

Slide 132 text

POST /like 201 Created

Slide 133

Slide 133 text

POST /like 201 Created

Slide 134

Slide 134 text

Channel Subscriber 1

Slide 135

Slide 135 text

POST /like Channel Subscriber 1 Update! Update!

Slide 136

Slide 136 text

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

Slide 137

Slide 137 text

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

Slide 138

Slide 138 text

GET /stream 200 OK Pushpin

Slide 139

Slide 139 text

Pushpin

Slide 140

Slide 140 text

Pushpin GET /stream

Slide 141

Slide 141 text

Pushpin GET /stream GET /stream

Slide 142

Slide 142 text

Pushpin GET /stream GET /stream Open #channel

Slide 143

Slide 143 text

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

Slide 144

Slide 144 text

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

Slide 145

Slide 145 text

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

Slide 146

Slide 146 text

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

Slide 147

Slide 147 text

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

Slide 148

Slide 148 text

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

Slide 149

Slide 149 text

PUSHPIN

Slide 150

Slide 150 text

PUSHPIN Transparent infrastructure layer

Slide 151

Slide 151 text

PUSHPIN Transparent infrastructure layer Independently scalable

Slide 152

Slide 152 text

PUSHPIN Transparent infrastructure layer Independently scalable Simple for clients

Slide 153

Slide 153 text

PUSHPIN Transparent infrastructure layer Independently scalable Simple for clients Open source

Slide 154

Slide 154 text

RECAP

Slide 155

Slide 155 text

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