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

Who are you?

•Technical

•Non-Technical

What do you want?

What are you hoping to take away from this session?


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

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


Constraint #2


Statelessness

Constraint #2

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

Statelessness

Constraint #3


Cacheability

Constraint #3

Cacheability

Request

Response

Copy ofResponse

Constraint #3

Cacheability

Request

Response

Constraint #3

Improves efficiency, scalability, perceived performance at cost of reliability


Cacheability

Constraint #4


Uniform Interface

Constraint #4

Uniform Interface

vs

Constraint #4

Enhances simplicity & visibility at the cost of efficiency


Uniform Interface

Constraint #5


Layered System

Constraint #5

Simplifies components at risk of increased latency for the whole


Layered System

Constraint #6


Code on Demand (optional)

Constraint #6

Potentially enhances client experience at the expense of visibility


Code on Demand (optional)


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


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


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


• Level 0 + Resources

• URIs are unique to resources

• Responses are Resource Representations


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


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


• Proper use of HTTP verbs

•GET• POST• PUT• PATCH•DELETE

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


•Generally also proper use of return codes

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


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


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

}



Response (200 OK):

{"payload": {

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

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

},"supplier": {...}

}}


Request (GET):

No Request Body

Resource-based URI

Appropriate Headers


• 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


•HATEOAS: Hypertext As The Engine Of Application State

• The responses document the API itself

•Makes it easier to change the API without impacting clients


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


Credit:LisaFrank


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?


• You aren’t resource-driven?

• Are your URIs resources?• Are your responses stateless

representations?


• 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

mike carey –restdone right -...

Documents