BEYOND REST

WEB SERVICES

DESIGNED

FOR MOBILE

tchacknight.com

Web ServicesNative Apps

Web ServicesNative Apps

People

TOPICS

Web API state of the art

TOPICS

Web API state of the art

Design considerations for developers

TOPICS

Web API state of the art

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

REST

Representational State Transfer

REST

Representational State Transfer

Coined by Roy Fielding in 2000

REST

Representational State Transfer

Coined by Roy Fielding in 2000

The architectural style of the web

REST

Representational State Transfer

Coined by Roy Fielding in 2000

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

nytimes.com

HATEOAS

HATEOAS

Client doesn’t need a manual

HATEOAS

Client doesn’t need a manual

Client doesn’t know URL formats

HATEOAS

Client doesn’t need a manual

Client doesn’t know URL formats

Client doesn’t know available states

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

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

1 2

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 a native wrapper like PhoneGap?

Use React Native?

HATEOAS

Use a native wrapper like PhoneGap?

Use React Native?

Something else?

HATEOAS

Use a native wrapper like PhoneGap?

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

FOR DEVELOPERSDOCUMENTATION

Treat it like any other feature

Must be up-to-date

FOR DEVELOPERSDOCUMENTATION

Treat it like any other feature

Must be up-to-date

Good: Auto-validate

FOR DEVELOPERSDOCUMENTATION

Treat it like any other feature

Must be up-to-date

Good: Auto-validate

Better: Auto-generate

FOR DEVELOPERSDOCUMENTATION

Treat it like any other feature

Must be up-to-date

Good: Auto-validate

Better: Auto-generate

Critical for developer happiness

FOR DEVELOPERSDOCUMENTATION

Reference

Troubleshooting

Change

FOR DEVELOPERSDOCUMENTATION

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

FOR DEVELOPERSDOCUMENTATION

Reference Docs Examples

https://stripe.com/docs/api

https://instagram.com/developer

https://developer.github.com/v3

FOR DEVELOPERSDOCUMENTATION

Troubleshooting

FOR DEVELOPERSDOCUMENTATION

Troubleshooting

Minimum: Detailed error messages

Better: Errors with links to reference docs

FOR DEVELOPERSDOCUMENTATION

Document Change

FOR DEVELOPERSDOCUMENTATION

Document Change

Minimum: Changelog

Better: Mailing list

CONSISTENCY

FOR DEVELOPERS

FOR DEVELOPERSCONSISTENCY

Don’t deviate from the norm

FOR DEVELOPERSCONSISTENCY

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

FOR DEVELOPERSCONSISTENCY

Provide consistent error responses

POST /sign_up

POST /sign_up

E

POST /sign_up

200 OKE

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✓

FOR DEVELOPERSCONSISTENCY

Use standard HTTP status codes

200 Success

201 Created

400 Bad request

401 Unauthorized

404 Not found

422 Unprocessable entity

500 Server error

FOR DEVELOPERSCONSISTENCY

Backwards compatibility

FOR DEVELOPERSCONSISTENCY

Backwards compatibility

Publish your contract

FOR DEVELOPERSCONSISTENCY

Backwards compatibility

Publish your contract

Adding new stuff is OK

FOR DEVELOPERSCONSISTENCY

Backwards compatibility

Publish your contract

Adding new stuff is OK

Removing stuff is not OK :(

FOR DEVELOPERSCONSISTENCY

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

FOR DEVELOPERSCONSISTENCY

How Stripe handles versions

FOR DEVELOPERSCONSISTENCY

How Stripe handles versions

Backwards compatibility is “hidden”

FOR DEVELOPERSCONSISTENCY

How Stripe handles versions

Backwards compatibility is “hidden”

New users are on the latest version

FOR DEVELOPERSCONSISTENCY

How Stripe handles versions

Backwards compatibility is “hidden”

New users are on the latest version

Stripe adds breaking changes with gates

FOR DEVELOPERSCONSISTENCY

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

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

Hypothetical situation

You have an app in the App Store

PATTERNSKILL SWITCH

Hypothetical situation

You have an app in the App Store

You discover a bug and start fixing it

PATTERNSKILL 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

PATTERNSKILL 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

PATTERNSKILL 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

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

PATTERNSSOURCE OF TRUTH

The server is always the source of truth

Except when it isn’t

PATTERNSSOURCE OF TRUTH

The server is always the source of truth

Except when it isn’t

What about when resources are created?

PATTERNSSOURCE 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?

PATTERNSSOURCE OF TRUTH

Keep it simple

PATTERNSSOURCE OF TRUTH

Keep it simple

Minimize client state

PATTERNSSOURCE OF TRUTH

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

POST /like

201 Created

POST /like

201 Created

POST /like

201 Created

Channel Subscriber 1

POST /like

Channel Subscriber 1

Update!

Update!

POST /like

Channel Subscriber 1

Update!

Update!

Subscriber 2

Update!

Subscriber 3

Update!

Channel Subscriber 1

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

GET /stream

200 OK chunked

GET /stream

Open #channel

Publish #channel

Publish #channel

Publish #channel

POST /like

POST /like

POST /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

Transparent infrastructure layer

Independently scalable

PUSHPIN

Transparent infrastructure layer

Independently scalable

Simple for clients

PUSHPIN

Transparent infrastructure layer

Independently scalable

Simple for clients

Open source

RECAP

Shared some tips and lessons learned

Importance of developer experience

Web API state of the art

RECAP

THANKS!

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

Sam Kirchmeier

@skirchmeier

THANKS!