beyond rest web services designed for mobile · beyond rest web services designed for mobile....

BEYOND REST

WEB SERVICES

DESIGNED

FOR MOBILE

tchacknight.com

Web ServicesNative Apps

Web ServicesNative Apps

People

TOPICS

Web API state of the art

TOPICS


Design considerations for developers

TOPICS


Design considerations for developers

Lessons and patterns

TOPICS

STATE OF THE ART

WHY REVIEW REST?

WHY REVIEW REST?

Defines our constraints

It might not be what you think it is

It’s really cool

REST

Representational State Transfer

REST


Coined by Roy Fielding in 2000

REST



The architectural style of the web

REST



The architectural style of the web

Deduced from and tested by the web itself

“[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 FieldingSource: https://www.ics.uci.edu/~fielding/pubs/dissertation/conclusions.htm

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

QUALITIES OF THE WEB

Simple

Proven

Scalable

Ubiquitous

QUALITIES OF THE WEB

Simple

Proven

Scalable

Ubiquitous

So aren’t all web APIs REST?

“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

HATEOAS

nytimes.com

HATEOAS

HATEOAS

Client doesn’t need a manual

HATEOAS


Client doesn’t know URL formats

HATEOAS



Client doesn’t know available states

HATEOAS



Client doesn’t know available states

Works for more than just read-only data

GET /sign_up

GET /sign_up

HTML <form>

GET /sign_up

HTML <form>

POST /sign_up

GET /sign_up

HTML <form>

POST /sign_up

200 OK

GET /sign_up

HTML <form>

1 2

GET /sign_up

HTML <form>

POST /sign_up

200 OK

1 2

GET /sign_up

HTML <form>

1 2

GET /sign_up

HTML <form>

POST /sign_up

ErrorE

1 2

GET /sign_up

HTML <form>

POST /sign_up

200 OK

C C

1 2

POST /sign_up

200 OK

CC

POST /sign_up

200 OK

CC

GET /sign_up

{ sign_up }

“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

POST /sign_up

200 OK

CC

GET /sign_up

{ sign_up }

CC

{ sign_up }

HATEOAS

Use a native wrapper like PhoneGap?

HATEOAS


Use React Native?

HATEOAS


Use React Native?

Something else?

HATEOAS


Use React Native?

Something else?

Compensate

“REST isn’t an all or nothing proposition.

One can get significant value from partial

adoption.”

–Sam RubySource: http://www.intertwingly.net/blog/2008/10/21/Progressive-Disclosure

CONSIDERATIONS

FOR DEVELOPERS

FOR DEVELOPERS

FOR DEVELOPERS

Documented

FOR DEVELOPERS

Documented

Consistent

FOR DEVELOPERS

Documented

Consistent

Testable

COUPLING &

PERMANENCE

C

DOCUMENTATION

FOR DEVELOPERS

FOR DEVELOPERSDOCUMENTATION

Treat it like any other feature



Must be up-to-date



Must be up-to-date

Good: Auto-validate



Must be up-to-date

Good: Auto-validate

Better: Auto-generate



Must be up-to-date

Good: Auto-validate

Better: Auto-generate

Critical for developer happiness


Reference

Troubleshooting

Change


Reference DocsAuthentication

Version Details

Request Headers

Response Headers

Response Format

Status Codes

Backwards Compatibility

Pagination

Resources

Methods

Method Parameters

Example Requests

Example Responses

Error Format


Reference Docs Examples

https://stripe.com/docs/api

https://instagram.com/developer

https://developer.github.com/v3


Troubleshooting


Troubleshooting

Minimum: Detailed error messages

Better: Errors with links to reference docs


Document Change


Document Change

Minimum: Changelog

Better: Mailing list

CONSISTENCY

FOR DEVELOPERS

FOR DEVELOPERSCONSISTENCY

Don’t deviate from the norm


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


Provide consistent error responses

POST /sign_up

POST /sign_up

E

POST /sign_up

200 OKE

POST /sign_up

200 OK

POST /sign_up

200 OK

E

E

POST /sign_up

200 OK

POST /sign_up

200 OK

E

EX

POST /sign_up

200 OK

POST /sign_up

422 Invalid

E

E✓


Use standard HTTP status codes

200 Success

201 Created

400 Bad request

401 Unauthorized

404 Not found

422 Unprocessable entity

500 Server error


Backwards compatibility



Publish your contract




Adding new stuff is OK





Removing stuff is not OK :(





Removing stuff is not OK :(

Making a backwards-incompatible change creates a new version of the API


How Stripe handles versions



Backwards compatibility is “hidden”




New users are on the latest version





Stripe adds breaking changes with gates





Stripe adds breaking changes with gates

Users can update to the latest anytime

TESTABLE

FOR DEVELOPERS

FOR DEVELOPERSTESTABLE

Web APIs must be testable

FOR DEVELOPERSTESTABLE

Web APIs must be testable

Minimum: Staging, Sandbox, or Test Mode

Better: Developers run a local server

LESSONS &

PATTERNS

PATTERNS

Kill switch

PATTERNS

Kill switch

Source of truth

PATTERNS

Kill switch

Source of truth

Pubsub

KILL SWITCH

PATTERNS

Can I have my data, please?

You need to upgrade, sorry!

:(

PATTERNSKILL SWITCH

A must have

PATTERNSKILL SWITCH

A must have

Minimum: Force an upgrade

PATTERNSKILL SWITCH

A must have

Minimum: Force an upgrade

Better: Communicate with users

PATTERNSKILL SWITCH

Hypothetical situation

PATTERNSKILL SWITCH


You have an app in the App Store

PATTERNSKILL SWITCH



You discover a bug and start fixing it

PATTERNSKILL SWITCH




Meanwhile, end users also discover it

PATTERNSKILL SWITCH





You’re helpless for 1 or 2 weeks

PATTERNSKILL SWITCH





You’re helpless for 1 or 2 weeks

Alert them

App version

Platform

OS version

Device

User-Agent MyApp/3.07.01 (Android; 5.0.2; Galaxy S6)

KILL SWITCH PATTERNS

SOURCE OF TRUTH

PATTERNS

PATTERNSSOURCE OF TRUTH

The server is always the source of truth



Except when it isn’t




What about when resources are created?




What about when resources are created?

What about airplane mode?


Keep it simple


Keep it simple

Minimize client state


Keep it simple

Minimize client state

Sync is an interesting, hard problem

PUBSUB

PATTERNS

PATTERNSPUBSUB

Publishers

Channels

Subscribers

PATTERNSPUBSUB

Publishers

Channels

Subscribers

Publishers and subscribers don’t know about each other

GET /stream

GET /stream

200 OK

POST /like

201 Created

Channel Subscriber 1

POST /like


Update!

Update!

POST /like


Update!

Update!

Subscriber 2

Update!

Subscriber 3

Update!


Update!

Subscriber 2

Update!

Subscriber 3

Update!

POST /like

Update!

GET /stream

200 OK

Pushpin

Pushpin

Pushpin

GET /stream

Pushpin

GET /streamGET /stream

Pushpin

GET /streamGET /stream

Open #channel

Pushpin

GET /stream

200 OK chunked

GET /stream

Open #channel

Pushpin

GET /stream

200 OK chunked

GET /stream

Open #channel

POST /like

Pushpin

GET /stream

200 OK chunked

GET /stream

Open #channel

Publish #channelPOST /like

Pushpin

GET /stream

200 OK chunked

GET /stream

Open #channel

Publish #channel

Publish #channel

Publish #channel

POST /like

POST /like

POST /like

PUSHPIN

PUSHPIN

Transparent infrastructure layer

PUSHPIN


Independently scalable

PUSHPIN



Simple for clients

PUSHPIN



Simple for clients

Open source

Shared some tips and lessons learned

Importance of developer experience


RECAP

THANKS!

https://github.com/livefront/beyond-rest

Sam Kirchmeier

@skirchmeier

THANKS!

beyond rest web services designed for mobile · beyond rest web services designed for mobile....

Documents