beyond rest web services designed for mobile · beyond rest web services designed for mobile....
TRANSCRIPT
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!