REST Best Practices D. Keith Casey, Jr Friday, February 15, 13 So - - PowerPoint PPT Presentation

▶
rest best practices
SMART_READER_LITE
LIVE PREVIEW

REST Best Practices D. Keith Casey, Jr Friday, February 15, 13 So - - PowerPoint PPT Presentation

Dec 03, 2022 384 likes •761 views

REST Best Practices D. Keith Casey, Jr Friday, February 15, 13 So who are you? D. Keith Casey, Jr General Annoyance, Blue Parabola Developer Evangelist, Twilio Project Lead, Web2Project Community: Helped organize php|tek*3,

slide-1
SLIDE 1

REST Best Practices

  • D. Keith Casey, Jr

Friday, February 15, 13

slide-2
SLIDE 2
  • D. Keith Casey, Jr - CodeWorks 2011

So who are you?

  • D. Keith Casey, Jr
  • General Annoyance, Blue Parabola
  • Developer Evangelist, Twilio
  • Project Lead, Web2Project
  • Community: Helped organize php|tek*3,

antagonized DCPHP, agitating in Austin PHP

Friday, February 15, 13

slide-3
SLIDE 3
  • D. Keith Casey, Jr - CodeWorks 2011

In the beginning...

  • We had single stack applications
  • Self-contained
  • Completely Independent
  • Built for humans by humans

Friday, February 15, 13

slide-4
SLIDE 4
  • D. Keith Casey, Jr - CodeWorks 2011

In the un-beginning...

  • Web Services
  • SOAP
  • XML-RPC
  • XML over HTTP
  • Other random junk..

Image Credit: Mashery.com

Friday, February 15, 13

slide-5
SLIDE 5
  • D. Keith Casey, Jr - CodeWorks 2011

Sanity: REST

  • Six Constraints
  • Client-Server
  • Stateless
  • Cacheable
  • Layered System
  • Uniform Interface
  • Code on Demand (optional)

Friday, February 15, 13

slide-6
SLIDE 6
  • D. Keith Casey, Jr - CodeWorks 2011

“Strictly RESTful”

REST is not a standard

Friday, February 15, 13

slide-7
SLIDE 7
  • D. Keith Casey, Jr - CodeWorks 2011

What REST is not..

  • Pretty URLs
  • XML over HTTP
  • JSON over HTTP

Friday, February 15, 13

slide-8
SLIDE 8
  • D. Keith Casey, Jr - CodeWorks 2011

“-ilities”

accessibility accountability accuracy adaptability administrability affordability agility auditability autonomy availability credibility process capabilities compatibility composability configurability correctness customizability debugability degradability determinability demonstrability dependability deployability discoverability distributability durability effectiveness efficiency evolvability extensibility failure transparency fault-tolerance fidelity flexibility inspectability installability Integrity interchangeability interoperability learnability maintainability manageability mobility modifiability modularity nomadicity operability orthogonality portability precision predictability producibility provability recoverability relevance reliability repeatability reproducibility resilience responsiveness reusability robustness safety scalability seamlessness self-sustainability serviceability (a.k.a. supportability) securability simplicity stability standards compliance senility survivability sustainability tailorability testability timeliness traceability ubiquity understandability upgradability usability

Friday, February 15, 13

slide-9
SLIDE 9
  • D. Keith Casey, Jr - CodeWorks 2011

“-ilities”

accessibility accountability accuracy adaptability administrability affordability agility auditability autonomy availability credibility process capabilities compatibility composability configurability correctness customizability debugability degradability determinability demonstrability dependability deployability discoverability distributability durability effectiveness efficiency evolvability extensibility failure transparency fault-tolerance fidelity flexibility inspectability installability Integrity interchangeability interoperability learnability maintainability manageability mobility modifiability modularity nomadicity operability orthogonality portability precision predictability producibility provability recoverability relevance reliability repeatability reproducibility resilience responsiveness reusability robustness safety scalability seamlessness self-sustainability serviceability (a.k.a. supportability) securability simplicity stability standards compliance senility survivability sustainability tailorability testability timeliness traceability ubiquity understandability upgradability usability

Friday, February 15, 13

slide-10
SLIDE 10
  • D. Keith Casey, Jr - CodeWorks 2011

Client-server

  • We get this one
  • By separating the two, we can vary them
  • Web servers & database servers
  • Scalability & Reliability

Friday, February 15, 13

slide-11
SLIDE 11
  • D. Keith Casey, Jr - CodeWorks 2011

Stateless

  • Each request stands on its own
  • This is where we struggle
  • Sessions, cookies, etc
  • Synchronization
  • Sticky sessions

Friday, February 15, 13

slide-12
SLIDE 12
  • D. Keith Casey, Jr - CodeWorks 2011

Stateless

curl -X POST 'https://api.twilio.com/ 2010-04-01/Accounts/ACxxxx/SMS/ Messages.xml' \

  • d 'From=%2B15125551212' \
  • d 'To=7035551212' \
  • d 'Body=This+is+just+a+test+message+to+see

+what+happens.' \

  • u ACxxxx:{AuthToken}

Friday, February 15, 13

slide-13
SLIDE 13
  • D. Keith Casey, Jr - CodeWorks 2011

Stateless - Why?

  • It’s WEB SCALE
  • Stability
  • Reliability
  • Flexibility

Friday, February 15, 13

slide-14
SLIDE 14
  • D. Keith Casey, Jr - CodeWorks 2011

Cacheable

  • GET, PUT, and DELETE should be idempotent or

“safe”

  • The word "safe" means that if a given HTTP

method is invoked, the resource state on the server remains unchanged.

  • POST... stupid POST

Friday, February 15, 13

slide-15
SLIDE 15
  • D. Keith Casey, Jr - CodeWorks 2011

... wha?

  • Within Twilio SMS:
  • /2010-04-01/Accounts/{AccountSid}/SMS/Messages
  • GET {optional: To, From, DateSent}
  • POST {required: To, From, Body ; optional: StatusCallback, ApplicationSid}
  • PUT n/a
  • DELETE n/a

Friday, February 15, 13

slide-16
SLIDE 16
  • D. Keith Casey, Jr - CodeWorks 2011

... wha?

  • Within Twilio Voice Recordings:
  • /2010-04-01/Accounts/{AccountSid}/Recordings/{RExxx}
  • GET {none}
  • POST n/a
  • PUT n/a
  • DELETE {none}

Friday, February 15, 13

slide-17
SLIDE 17
  • D. Keith Casey, Jr - CodeWorks 2011

Layered System

  • Don’t count on the Client communicating

directly to the Server

  • We use this on the web every single day
  • Adds silent, invisible dependencies

Friday, February 15, 13

slide-18
SLIDE 18
  • D. Keith Casey, Jr - CodeWorks 2011

Layered System - Why?

  • Don’t count on the Client communicating

directly to the Server

  • Allows
  • Load Balancers, Caches
  • Logging, Audit trails
  • Authentication & Authorization

Friday, February 15, 13

slide-19
SLIDE 19
  • D. Keith Casey, Jr - CodeWorks 2011

Skynet Day

Ref: http://www.twilio.com/engineering/2011/04/22/why-twilio-wasnt-affected-by-todays-aws-issues

Friday, February 15, 13

slide-20
SLIDE 20
  • D. Keith Casey, Jr - CodeWorks 2011

Code on Demand

(optional)

  • A request doesn’t just retrieve a resource but

also the code to act upon it

  • We don’t have to know or understand the

code, just how to run it

  • Allows for flexibility, upgradability

Friday, February 15, 13

slide-21
SLIDE 21
  • D. Keith Casey, Jr - CodeWorks 2011

Ummm... gmail?

Friday, February 15, 13

slide-22
SLIDE 22
  • D. Keith Casey, Jr - CodeWorks 2011

Uniform Interfaces

  • Four Principles
  • Identification of Resources
  • Manipulation of Resources through these Representations
  • Self-descriptive Messages
  • Hypermedia as the engine of application state (HATEOAS)

Friday, February 15, 13

slide-23
SLIDE 23
  • D. Keith Casey, Jr - CodeWorks 2011

Identification of Resources

  • Generally
  • /noun/id
  • /noun/action/id
  • But not required
  • /?n=noun&id=id
  • /?n=noun&a=action&id=id

Friday, February 15, 13

slide-24
SLIDE 24
  • D. Keith Casey, Jr - CodeWorks 2011

Manipulation through those Interfaces

  • Within Twilio:
  • /2010-04-01/Accounts/{AccountSid}/Calls/{CAxxx}
  • /2010-04-01/Accounts/{AccountSid}/Conferences/{CFxxx}
  • /2010-04-01/Accounts/{AccountSid}/Notifications/{NOxxx}
  • /2010-04-01/Accounts/{AccountSid}/Recordings/{RExxx}
  • /2010-04-01/Accounts/{AccountSid}/SMS/{SMxxx}
  • /2010-04-01/Accounts/{AccountSid}/Transcripts/{TRxxx}
  • GET {none}
  • POST {only for Calls & SMS}
  • PUT n/a
  • DELETE {only for Recordings}

Friday, February 15, 13

slide-25
SLIDE 25
  • D. Keith Casey, Jr - CodeWorks 2011

Self Descriptive

  • Each message should tell you:
  • how to process itself;
  • how to request the next resource;
  • if that resource is cachable;

Friday, February 15, 13

slide-26
SLIDE 26
  • D. Keith Casey, Jr - CodeWorks 2011

HATEOAS

Clients make state transitions only through actions that are dynamically identified within hypermedia by the server (e.g. by hyperlinks within hypertext). Except for simple fixed entry points to the application, a client does not assume that any particular actions will be available for any particular resources beyond those described in representations previously received from the server.

Source: http://en.wikipedia.org/wiki/Representational_state_transfer#RESTful_web_services

Friday, February 15, 13

slide-27
SLIDE 27
  • D. Keith Casey, Jr - CodeWorks 2011

HATEOAS - not good

$ curl -I https://api.github.com/ HTTP/1.1 302 Found Server: nginx/1.0.4 Content-Type: text/html;charset=utf-8 Connection: keep-alive Status: 302 Found X-RateLimit-Limit: 5000 Location: http://developer.github.com X-RateLimit-Remaining: 4993 Content-Length: 0

Friday, February 15, 13

slide-28
SLIDE 28
  • D. Keith Casey, Jr - CodeWorks 2011

HATEOAS - good

$ curl https://api.twilio.com/2010-04-01 <?xml version="1.0"?> <TwilioResponse> <Version> <Name>2010-04-01</Name> <Uri>/2010-04-01</Uri> <SubresourceUris> <Accounts>/2010-04-01/Accounts</Accounts> </SubresourceUris> </Version> </TwilioResponse>

Friday, February 15, 13

slide-29
SLIDE 29
  • D. Keith Casey, Jr - CodeWorks 2011

HATEOAS - more good

<TwilioResponse> <Account> <Sid>ACxxxx</Sid> <FriendlyName>Do you like my friendly name?</FriendlyName> <Type>Full</Type> <Status>active</Status> <DateCreated>Wed, 04 Aug 2010 21:37:41 +0000</DateCreated> <DateUpdated>Fri, 06 Aug 2010 01:15:02 +0000</DateUpdated> <AuthToken>redacted</AuthToken> <Uri>/2010-04-01/Accounts/ACxxxx</Uri> <SubresourceUris> <AvailablePhoneNumbers>/2010-04-01/Accounts/ACxxxx/AvailablePhoneNumbers</AvailablePhoneNumbers> <Calls>/2010-04-01/Accounts/ACxxxx/Calls</Calls> <Conferences>/2010-04-01/Accounts/ACxxxx/Conferences</Conferences> <IncomingPhoneNumbers>/2010-04-01/Accounts/ACxxxx/IncomingPhoneNumbers</IncomingPhoneNumbers> <Notifications>/2010-04-01/Accounts/ACxxxx/Notifications</Notifications> <OutgoingCallerIds>/2010-04-01/Accounts/ACxxxx/OutgoingCallerIds</OutgoingCallerIds> <Recordings>/2010-04-01/Accounts/ACxxxx/Recordings</Recordings> <Sandbox>/2010-04-01/Accounts/ACxxxx/Sandbox</Sandbox> <SMSMessages>/2010-04-01/Accounts/ACxxxx/SMS/Messages</SMSMessages> <Transcriptions>/2010-04-01/Accounts/ACxxxx/Transcriptions</Transcriptions> </SubresourceUris> </Account> </TwilioResponse>

Friday, February 15, 13

slide-30
SLIDE 30
  • D. Keith Casey, Jr - CodeWorks 2011

HATEOAS - more good

<TwilioResponse> <Account> <Sid>ACxxxx</Sid> <FriendlyName>Do you like my friendly name?</FriendlyName> <Type>Full</Type> <Status>active</Status> <DateCreated>Wed, 04 Aug 2010 21:37:41 +0000</DateCreated> <DateUpdated>Fri, 06 Aug 2010 01:15:02 +0000</DateUpdated> <AuthToken>redacted</AuthToken> <Uri>/2010-04-01/Accounts/ACxxxx</Uri> <SubresourceUris> <AvailablePhoneNumbers>/2010-04-01/Accounts/ACxxxx/AvailablePhoneNumbers</AvailablePhoneNumbers> <Calls>/2010-04-01/Accounts/ACxxxx/Calls</Calls> <Conferences>/2010-04-01/Accounts/ACxxxx/Conferences</Conferences> <IncomingPhoneNumbers>/2010-04-01/Accounts/ACxxxx/IncomingPhoneNumbers</IncomingPhoneNumbers> <Notifications>/2010-04-01/Accounts/ACxxxx/Notifications</Notifications> <OutgoingCallerIds>/2010-04-01/Accounts/ACxxxx/OutgoingCallerIds</OutgoingCallerIds> <Recordings>/2010-04-01/Accounts/ACxxxx/Recordings</Recordings> <Sandbox>/2010-04-01/Accounts/ACxxxx/Sandbox</Sandbox> <SMSMessages>/2010-04-01/Accounts/ACxxxx/SMS/Messages</SMSMessages> <Transcriptions>/2010-04-01/Accounts/ACxxxx/Transcriptions</Transcriptions> </SubresourceUris> </Account> </TwilioResponse>

Friday, February 15, 13

slide-31
SLIDE 31
  • D. Keith Casey, Jr - CodeWorks 2011

HATEOAS - more good

<TwilioResponse> <Account> <Sid>ACxxxx</Sid> <FriendlyName>Do you like my friendly name?</FriendlyName> <Type>Full</Type> <Status>active</Status> <DateCreated>Wed, 04 Aug 2010 21:37:41 +0000</DateCreated> <DateUpdated>Fri, 06 Aug 2010 01:15:02 +0000</DateUpdated> <AuthToken>redacted</AuthToken> <Uri>/2010-04-01/Accounts/ACxxxx</Uri> <SubresourceUris> <AvailablePhoneNumbers>/2010-04-01/Accounts/ACxxxx/AvailablePhoneNumbers</AvailablePhoneNumbers> <Calls>/2010-04-01/Accounts/ACxxxx/Calls</Calls> <Conferences>/2010-04-01/Accounts/ACxxxx/Conferences</Conferences> <IncomingPhoneNumbers>/2010-04-01/Accounts/ACxxxx/IncomingPhoneNumbers</IncomingPhoneNumbers> <Notifications>/2010-04-01/Accounts/ACxxxx/Notifications</Notifications> <OutgoingCallerIds>/2010-04-01/Accounts/ACxxxx/OutgoingCallerIds</OutgoingCallerIds> <Recordings>/2010-04-01/Accounts/ACxxxx/Recordings</Recordings> <Sandbox>/2010-04-01/Accounts/ACxxxx/Sandbox</Sandbox>

<SMSMessages>/2010-04-01/Accounts/ACxxxx/SMS/Messages</SMSMessages>

<Transcriptions>/2010-04-01/Accounts/ACxxxx/Transcriptions</Transcriptions> </SubresourceUris> </Account> </TwilioResponse>

Friday, February 15, 13

slide-32
SLIDE 32
  • D. Keith Casey, Jr - CodeWorks 2011

HATEOAS - more good

<TwilioResponse> <Account> <Sid>ACxxxx</Sid> <FriendlyName>Do you like my friendly name?</FriendlyName> <Type>Full</Type> <Status>active</Status> <DateCreated>Wed, 04 Aug 2010 21:37:41 +0000</DateCreated> <DateUpdated>Fri, 06 Aug 2010 01:15:02 +0000</DateUpdated> <AuthToken>redacted</AuthToken> <Uri>/2010-04-01/Accounts/ACxxxx</Uri> <SubresourceUris> <AvailablePhoneNumbers>/2010-04-01/Accounts/ACxxxx/AvailablePhoneNumbers</AvailablePhoneNumbers> <Calls>/2010-04-01/Accounts/ACxxxx/Calls</Calls> <Conferences>/2010-04-01/Accounts/ACxxxx/Conferences</Conferences> <IncomingPhoneNumbers>/2010-04-01/Accounts/ACxxxx/IncomingPhoneNumbers</IncomingPhoneNumbers>

<Notifications>/2010-04-01/Accounts/ACxxxx/Notifications</Notifications>

<OutgoingCallerIds>/2010-04-01/Accounts/ACxxxx/OutgoingCallerIds</OutgoingCallerIds> <Recordings>/2010-04-01/Accounts/ACxxxx/Recordings</Recordings> <Sandbox>/2010-04-01/Accounts/ACxxxx/Sandbox</Sandbox> <SMSMessages>/2010-04-01/Accounts/ACxxxx/SMS/Messages</SMSMessages> <Transcriptions>/2010-04-01/Accounts/ACxxxx/Transcriptions</Transcriptions> </SubresourceUris> </Account> </TwilioResponse>

Friday, February 15, 13

slide-33
SLIDE 33
  • D. Keith Casey, Jr - CodeWorks 2011
  • ilities

accessibility accountability accuracy adaptability administrability affordability agility auditability autonomy availability credibility process capabilities compatibility composability configurability correctness customizability debugability degradability determinability demonstrability dependability deployability discoverability distributability durability effectiveness efficiency evolvability extensibility failure transparency fault-tolerance fidelity flexibility inspectability installability Integrity interchangeability interoperability learnability maintainability manageability mobility modifiability modularity nomadicity operability orthogonality portability precision predictability producibility provability recoverability relevance reliability repeatability reproducibility resilience responsiveness reusability robustness safety scalability seamlessness self-sustainability serviceability (a.k.a. supportability) securability simplicity stability standards compliance sterility survivability sustainability tailorability testability timeliness traceability ubiquity understandability upgradability usability

Friday, February 15, 13

slide-34
SLIDE 34
  • D. Keith Casey, Jr - CodeWorks 2011

REST vs OOP

  • REST Constraints
  • Client-Server
  • Stateless
  • Cacheable
  • Layered System
  • Uniform Interface
  • Code on Demand

(optional)

  • OOP Principles
  • Single Responsibility
  • Open/Closed
  • Liskov Substitution
  • Interface Segregation
  • Dependency Inversion

Friday, February 15, 13

slide-35
SLIDE 35
  • D. Keith Casey, Jr - CodeWorks 2011

Additional Resources

(no pun intended)

  • http://en.wikipedia.org/wiki/HATEOAS
  • http://blog.steveklabnik.com/2011/07/03/nobody-

understands-rest-or-http.html - Steve Klabnik

  • http://shop.oreilly.com/product/9780596529260.do
  • http://videos.restfest.org
  • http://devzone.zend.com/1915/solid-oo-principles/

Friday, February 15, 13

slide-36
SLIDE 36
  • D. Keith Casey, Jr - CodeWorks 2011
  • D. Keith Casey, Jr.

keith@twilio.com keith@blueparabola.com keith@caseysoftware.com caseysoftware just about everywhere online

For Twilio Txt: [redacted]

Friday, February 15, 13