mike carey –restdone right -...

Mike Carey – ReST Done RightNovember 2017

Meet Mike

2008:JavaEngineeratWalmart

2010:IntroducedtoAgile(Scrum)

2011:AgileUserGroup/ScrumMaster

2013:AgileCoach

2015:DeliveryManagerinD.C.Office

2017:WalmartLabs

Assumptions & BaselineReST TheoryReST in the WildSo What?

Talking Points

01020304

Assumptions & BaselineReST TheoryReST in the WildSo What?

Talking Points

01020304

Who are you?

•Technical

•Non-Technical

What do you want?

What are you hoping to take away from this session?

Assumptions & BaselineReST TheoryReST in the WildSo What?

Talking Points

01020304

All the Buzzwords!

Credit:http://hyperboleandahalf.blogspot.com/2010/06/this-is-why-ill-never-be-adult.html

All the Buzzwords!

• Service-Oriented Architecture (SOA)

•Microservices

• Representational State Transfer (ReST)

Where did ReST come from?

Where did ReST come from?

• Dr. Roy Fielding’s 2000 Dissertation, “Architectural Styles andthe Design of Network-based Software Architectures”

• Written as a result of defending the design choices of the Internet for 4 years in the late ‘90s

Why is ReST important?

• Defines a “core set of principles, properties, and constraints”

• Leverages existing HTTP standards

• Provides greater flexibility than SOAP, other protocols

Let’s ReST!

RepresentationalStateTransfer

Let’s ReST!

RepresentationalStateTransfer

Let’s ReST!

RepresentationalStateTransfer

Let’s ReST!

RepresentationalStateTransfer

Constraint #1

Client-Server Architecture

Credit: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Constraint #1

Client-Server Architecture

Credit: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Constraint #1

Client-Server Architecture

Allows for independent scaling of each

Credit: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Constraint #2

Credit: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Statelessness

Constraint #2

Credit: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Statelessness

Constraint #2

Allows for visibility, reliability, and scalabilityCredit: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Statelessness

Constraint #3

Credit: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Cacheability

Constraint #3

Cacheability

Request

Response

Copy ofResponse

Constraint #3

Cacheability

Request

Response

Constraint #3

Improves efficiency, scalability, perceived performance at cost of reliability

Credit: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Cacheability

Constraint #4

Credit: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Uniform Interface

Constraint #4

Uniform Interface

vs

Constraint #4

Enhances simplicity & visibility at the cost of efficiency

Credit: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Uniform Interface

Constraint #5

Credit: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Layered System

Constraint #5

Simplifies components at risk of increased latency for the whole

Credit: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Layered System

Constraint #6

Credit: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Code on Demand (optional)

Constraint #6

Credit: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Code on Demand (optional)

Constraint #6

Potentially enhances client experience at the expense of visibility

Credit: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Code on Demand (optional)

Assumptions & BaselineReST TheoryReST in the WildSo What?

Talking Points

01020304

Where the Wild Things Are

Credit: Maurice Sendak, “Where the Wild Things Are”

Richardson Maturity Model

• Defined by Leonard Richardson in 2008 (?)

• Best explained by Martin Fowler in 2010

• Presented to you with real life(ish) examples

Richardson Maturity Model – Level 0

• Uses HTTP as transport system

•Does not leverage HTTP mechanisms, i.e.•Methods/Verbs• Response Codes

• SOAP, XML-RPC

Richardson Maturity Model – Level 0

Request (POST):

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

<SOAP-ENV:Header/><SOAP-ENV:Body>

<ns4:getItemDetails xmlns:ns3="http://xmlns.walmartstores.com/ns3Path" xmlns:ns4="http://xmlns.walmartstores.com/ns4Path" xmlns:ns5="http://xmlns.walmartstores.com/ns5Path">

<upcNumber>4391797660</upcNumber></ns4:getItemDetails>

</SOAP-ENV:Body></SOAP-ENV:Envelope>

Response (200 OK):

<soapenv:Envelopexmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">

<soapenv:Header><wsse:Security xmlns:wsse="http://docs.oasis-

open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" soapenv:mustUnderstand="1"/>

</soapenv:Header><soapenv:Body>

<n:getItemDetailsResponsexmlns:n="http://www.xmlns.walmartstores.com/nPath">

<return><errors>Error Code:1000

</errors></return></n:getItemDetailsResponse>

</soapenv:Body></soapenv:Envelope>

URI: http://www.hostname.com/path/GetItemInfo

Richardson Maturity Model – Level 0

Request (POST):

{"arg0": {

"authMethod":"","countryCd":"US","itemInfo":[{

"upc":"000004391797660"}],"languageCd":"ENG","reqDateTime":"2017-10-24","storeNbr":100

}}

Response (200 OK):

{"messageFault": {

"errorCode":200,"errorNode":null,"errorDesc":null,"errorText":"Success"

},"item": {

"details": {...

},..."xparams":null

}}

URI: http://www.hostname.com/path/GetItemInfo

Richardson Maturity Model – Level 1

• Level 0 + Resources

• URIs are unique to resources

• Responses are Resource Representations

Richardson Maturity Model – Level 1

Request (POST):

{"arg0": {

"authMethod":"","countryCd":"US","itemInfo":[{

"upc":"000004391797660"}],"languageCd":"ENG","reqDateTime":"2017-10-24","storeNbr":100

}}

Response (200 OK):

{"payload": {

"item": {"itemName": "FRONTLINE LARGE DOG","upc": "0000350604287200","multiPackStatus": false,"hazMat": false,"hazwaste": false,...

},"supplier": {...}

}}

URI: http://www.hostname.com/path/items/123456

Richardson Maturity Model – Level 1

• I have not encountered in the wild

• If they think to use resources,they usually think to use HTTP verbs

Credit:http://pbfcomics.com/comics/the-last-unicorns/

Richardson Maturity Model – Level 2

• Proper use of HTTP verbs

•GET• POST• PUT• PATCH•DELETE

• Read• Create• Update (wholesale)• Update (partial)•Delete

Richardson Maturity Model – Level 2

•Generally also proper use of return codes

• 200 OK• 400 BAD REQUEST• 404 NOT FOUND• 418 I’M A TEAPOT• 500 INTERNAL SERVER ERROR

Richardson Maturity Model – Level 2

• 62 Standard codes•Organized by category• 1xx: Informational• 2xx: Success• 3xx: Redirection• 4xx: Client Error• 5xx: Server Error

Richardson Maturity Model – Level 2

Request (GET):

No Request Body

Resource-based URI

Appropriate Headers

Response (404 NOT FOUND):

{"status": "NOT_FOUND”,"header": {

"headerAttributes": {}},"errors": [

{"code": "404.LOOKUP_SERVICE.1001","field": "”,"description": "Item details not found.","info": "","severity": "ERROR","category": "REQUEST","causes": [],"errorIdentifiers": {}

}],"payload": null

}

URI: http://www.hostname.com/path/items/123456

Richardson Maturity Model – Level 2

Response (200 OK):

{"payload": {

"item": {"itemName": "FRONTLINE LARGE DOG","upc": "0000350604287200","multiPackStatus": false,

"hazMat": false,"hazwaste": false,...

},"supplier": {...}

}}

URI: http://www.hostname.com/path/items/123456

Request (GET):

No Request Body

Resource-based URI

Appropriate Headers

Richardson Maturity Model – Level 2

• At level two, you are satisfying up to 5½ of the 6 constraints

• For internal-use ReST, often hit point of diminishing returns past level 2

Richardson Maturity Model – Level 3

•HATEOAS: Hypertext As The Engine Of Application State

• The responses document the API itself

•Makes it easier to change the API without impacting clients

Richardson Maturity Model – Level 3

GET Response:

{"payload": [

{"upc": "0000350604287200",...,"details": "/items/123456"

},{

"upc": "0000681131159430",...,"details": "/items/789012"

},...

]}

GET Response:

{"payload": {

"item": {"itemName": "FRONTLINE LARGE DOG","upc": "0000350604287200","multiPackStatus": false,

"hazMat": false,"hazwaste": false,...

},"supplier": "/suppliers/123456"

}}

URI: http://www.hostname.com/path/items URI: http://www.hostname.com/path/items/123456

Richardson Maturity Model – Level 3

Credit:LisaFrank

Assumptions & BaselineReST TheoryReST in the WildSo What?

Talking Points

01020304

Ask yourself

•Why am I building this API?

•Where are the capability boundaries?

•Who might my consumers be?

What happens when…

• You aren’t right-sized and cohesive?

• Are you violating the:• Client-Server Architecture constraint?• Layered System constraint?

What happens when…

• You aren’t resource-driven?

• Are your URIs resources?• Are your responses stateless

representations?

What happens when…

• You don’t leverage HTTP standards?

•How easy is your API to• Consume?• Cache?• Change?

“”To succeed in this world, you have to change all the time.

Sam Walton, Walmart Founder