icsoc 2008 summer school session on rest-based services · drink made drink released lookup next...
TRANSCRIPT
REST-based Web Services (II)
Helen Paik
School of Computer Science and EngineeringUniversity of New South Wales
Resources:
RESTful Web Services by L. Richardson and S. Ruby, O’Reilly
Building Web Services the REST Way, By Roger L. Costello –http://www.xfront.com/REST-Web-Services.html
ICSOC 2008 Summer School session on REST-based Services
article: How to get a cup of coffee by Jim Webber(http://www.infoq.com/articles/webber-rest-workflow)
Week 7
H. Paik (CSE, UNSW) REST Week 7 1 / 61
On POST and PUT
POST creates a new resource
But ... the server decides on that resource’s URI and returns the newURI for the resource in the response
Common human Web example:
posting to Web log: Server decides URI of posting and any commentsmade on that postcreating a new employee, a new order, etc.
H. Paik (CSE, UNSW) REST Week 7 2 / 61
On POST and PUT
PUT “creates” or “updates” a resource:
HTTP spec says: PUT method requests that the enclosed entitybe stored under the supplied Request-URI. If the Request-URIrefers to an already existing resource, the enclosed entitySHOULD be considered as a modified version of the one residingon the origin server. If the Request-URI does not point to anexisting resource, and that URI is capable of being defined as anew resource by the requesting user agent, the origin server cancreate the resource with that URI.
Use PUT to create a new resource when you know the URI for the newresource.
Always use PUT to update an existing resource
H. Paik (CSE, UNSW) REST Week 7 3 / 61
Business Processes/Workflow and REST
Take the Coffee Order Process from Jim Webber as example ...
The customer workflow:
OrderPlaced
OrderUpdated
Paid DrinkReceivedPlace Order Pay Pickup
Order Updated
Update AcceptedUpdate Rejected
customers advance towards the goal of drinking some coffee byinteracting with the Starbucks service,the customer orders, pays, and waits for the drink,between ‘order’ and ‘pay’, the customer can update (asking forskimmed milk)
H. Paik (CSE, UNSW) REST Week 7 4 / 61
Business Processes/Workflow and REST
The barista workflow:
OrderChosen
DrinkMade
DrinkReleased
LookupNext Order
MakeDrink
Take Payment
LookupNext Order
the barista loops around looking for the next order to be made,preparing the drink, and taking the payment,
The outputs of the workflow are available to the customer when thebarista finishes the order and releases the drink
Points to Remember: We will see how each transition in two statemachines is implemented as an interaction with a Web resource. Eachtransition is the combination of a HTTP verb on a resource via its URIcausing state changes.
H. Paik (CSE, UNSW) REST Week 7 5 / 61
Customer’s View Point: I want to order a coffee ...
Placing an Order
•! Place your order by POSTing it to a well-known URI
–! http://example.starbucks.com/order
H4"&(1$
31,'9:06;)$3&'?"0&$
64 © ThoughtWorks 2008
H. Paik (CSE, UNSW) REST Week 7 6 / 61
POST and its RESPONSE
Placing an Order: On the Wire
•! Request POST /order HTTP 1.1
Host: starbucks.example.org
Content-Type: application/xml
Content-Length: ...
<order xmlns="urn:starbucks">
<drink>latte</drink>
</order>
•! Response 201 Created
Location: http://
starbucks.example.org/order?1234
Content-Type: application/xml
Content-Length: ...
<order xmlns="urn:starbucks">
<drink>latte</drink>
<link rel="payment"
href="https://starbucks.example.org/payment/order?1234"
type="application/xml"/>
</order>
C$4"(6G$K)$1.")$1.&$)1,'1$
5E$,($CLKW$
65 © ThoughtWorks 2008
H. Paik (CSE, UNSW) REST Week 7 7 / 61
Customer: I want to update my order ... ?
Whoops! A mistake
•! I like my coffee to taste like coffee!
•! I need another shot of espresso
–! What are my OPTIONS?
!!I&Z:&)1$OPTIONS /order?1234 HTTP 1.1
Host: starbucks.example.org
!!I&)-5()&$200 OK
Allow: GET, PUT L.&<G$K$0,($
:-@,1&$#/$5'@&'8$
E5'$(5<$
66 © ThoughtWorks 2008
H. Paik (CSE, UNSW) REST Week 7 8 / 61
Optional: Look Before You Leap
•! See if the resource has changed since you submitted your order
–! If you’re fast your drink hasn’t been prepared yet
!!I&Z:&)1$PUT /order?1234 HTTP 1.1
Host: starbucks.example.org
Expect: 100-Continue
!!I&)-5()&$100 Continue
K$0,($)R44$LA!$1.")$
'&)5:'0&8$E5'$(5<D$
2[\]$QM-&01,R5($J,"4&@$
51.&'<")&=$
67 © ThoughtWorks 2008
H. Paik (CSE, UNSW) REST Week 7 9 / 61
Now go ahead and update ...
Amending an Order
•! Add specialities to you order via PUT
–! Starbucks needs 2 shots!
H4"&(1$
31,'9:06;)$3&'?"0&$
68 © ThoughtWorks 2008
H. Paik (CSE, UNSW) REST Week 7 10 / 61
PUT and its RESPONSE
Amending an Order: On the Wire
•! Request PUT /order?1234 HTTP 1.1
Host: starbucks.example.org
Content-Type: application/xml
Content-Length: ...
<order xmlns="urn:starbucks">
<drink>latte</drink>
<additions>shot</additions>
<link rel="payment" href="https://starbucks.example.org/payment/order?1234"
type="application/xml"/>
</order>
•! Response 200 OK
Location: http://starbucks.example.org/order?1234
Content-Type: application/xml
Content-Length: ...
<order xmlns="urn:starbucks">
<drink>latte</drink>
<additions>shot</additions>
<link rel="payment" href="https://starbucks.example.org/payment/order?1234"
type="application/xml"/>
</order>
69 © ThoughtWorks 2008
H. Paik (CSE, UNSW) REST Week 7 11 / 61
Statelessness at work ...
Remember interactions with resources are stateless
The resource “forgets” about you while you’re not directly interactingwith it
Which means race conditions are possible ...
A good/responsible practice for updating a resource:
Use If-Unmodified-Since on a timestamp to make sure no one elsehas change the resource since last time you checked !!
Or use If-Match and an ETag, instead of the timestamp
If the condition check fails (i.e., the resource has changed since), youwill get a 412 PreconditionFailed – i.e., you will avoid gettingunexpected response ...
H. Paik (CSE, UNSW) REST Week 7 12 / 61
Warning: Don’t be Slow!
•! Can only make changes until someone actually makes your drink
–! You’re safe if you use If-Unmodified-Since or If-Match
–! But resource state can change without you!
!!I&Z:&)1$PUT /order?1234 HTTP 1.1
Host: starbucks.example.org
...
!!I&)-5()&$409 Conflict
!55$)45<G$35#&5(&$&4)&$.,)$
0.,(7&@$1.&$)1,1&$5E$#/$5'@&'$
!!I&Z:&)1$OPTIONS /order?1234 HTTP 1.1
Host: starbucks.example.org
!!I&)-5()&$Allow: GET
71 © ThoughtWorks 2008
H. Paik (CSE, UNSW) REST Week 7 13 / 61
Customer: Order update successful, what now ...?
Order Confirmation: On the Wire
•! Request GET /order?1234 HTTP 1.1
Host: starbucks.example.org
Content-Type: application/xml
Content-Length: ...
•! Response 200 OK
Location: http://starbucks.example.org/order?1234
Content-Type: application/xml
Content-Length: ...
<order xmlns="urn:starbucks">
<drink>latte</drink>
<additions>shot</additions>
<link rel="payment" href="https://starbucks.example.org/payment/order?1234"
type="application/xml"/>
</order>
C'&$1.&/$1'/"(7$15$1&44$#&$
)5#&1."(7$<"1.$./-&'#&@",W$
72 © ThoughtWorks 2008
H. Paik (CSE, UNSW) REST Week 7 14 / 61
Order Payment
•! PUT your payment to the order resource https://starbucks.example.org/payment/order?1234
H4"&(1$
31,'9:06;)$3&'?"0&$
X&<$'&)5:'0&G$.^-)_``)1,'9:06)D&M,#-4&D5'7`-,/#&(1`5'@&'W\ab[$
73 © ThoughtWorks 2008
H. Paik (CSE, UNSW) REST Week 7 15 / 61
How did I know to PUT?
•! The client knew the URI to PUT to from the link
–! PUT is also idempotent (can safely re-try) in case of failure
•! Verified with OPTIONS
–! Just in case you were in any doubt !
!!I&Z:&)1$OPTIONS /payment/order?1234 HTTP 1.1
Host: starbucks.example.org
!!I&)-5()&$Allow: GET, PUT
74 © ThoughtWorks 2008
H. Paik (CSE, UNSW) REST Week 7 16 / 61
Order Payment: On the Wire
•! Request PUT /payment/order?1234 HTTP 1.1
Host: starbucks.example.org
Content-Type: application/xml
Content-Length: ...
<payment xmlns="urn:starbucks">
<cardNo>123456789</cardNo>
<expires>07/07</expires>
<name>John Citizen</name>
<amount>4.00</amount>
</payment>
•! Response 201 Created
Location: https://starbucks.example.org/payment/order?1234
Content-Type: application/xml
Content-Length: ...
<payment xmlns="urn:starbucks">
<cardNo>123456789</cardNo>
<expires>07/07</expires>
<name>John Citizen</name>
<amount>4.00</amount>
</payment>
75 © ThoughtWorks 2008
H. Paik (CSE, UNSW) REST Week 7 17 / 61
Check that you’ve paid
•! Request GET /order?1234 HTTP 1.1
Host: starbucks.example.org
Content-Type: application/xml
Content-Length: ...
•! Response 200 OK
Content-Type: application/xml
Content-Length: ...
<order xmlns="urn:starbucks">
<drink>latte</drink>
<additions>shot</additions>
</order>
T/$OCLKP$.,)$0.,(7&@8$
9&0,:)&$K;?&$-,"@$&(5:7.$
(5<$
76 © ThoughtWorks 2008
H. Paik (CSE, UNSW) REST Week 7 18 / 61
The Barista’s view point: What are current orders?
A simple GET on a URI – GET will return outstanding orders as a Webfeed. http://starbucks.example.org/orders
This is going to be polled regularlyH. Paik (CSE, UNSW) REST Week 7 19 / 61
Barista: OK, Got the order. You can’t change it now
When the barista begins to prepare our coffee, the state of the ordershould change so that no further updates are allowed.
“Follow” an entry in the order list to get the details of the order (i.e., GETon the resource):
H. Paik (CSE, UNSW) REST Week 7 20 / 61
Barista: Update the order status
Follow the edit link, then issue “PUT” on the resource.
After this, it will reject anything other than GET requests to the/orders/1234 resource.
H. Paik (CSE, UNSW) REST Week 7 21 / 61
Barista: Delete the order from the queue now ...
When the coffee is released to the customer, the order resource is deletedfrom the queue, the barista yes on to the next order ...
Of course, deleting the order can be done by issuing:
DELETE /order/1234 HTTP 1.1Host: starbucks.example.org
H. Paik (CSE, UNSW) REST Week 7 22 / 61
Finally drink your coffee...
35:'0&_$.^-_``"#,7&)D9:)"(&))<&&6D05#`))`cd`c]`15-e9',(@)`"#,7&`)1,'9:06)DF-7$
77 © ThoughtWorks 2008
H. Paik (CSE, UNSW) REST Week 7 23 / 61
Changing the Starbucks workflow ?
OrderPlaced
OrderUpdated
Paid DrinkReceivedPlace Order
coupon
Pickup
Order Updated
Update AcceptedUpdate Rejected
CouponOffered
pay
If the self-describing nature of the workflow (i.e., links) is well-respected,the client should not be surprised by the changes !
H. Paik (CSE, UNSW) REST Week 7 24 / 61
Lessons from Starbucks ...
A workflow can be implemented via combining HTTP verbs onresources
HTTP has a header/status combination for every occasion (especiallyuseful when things go wrong or are uncertain)
APIs are expressed in terms of links, and links are great !!
XML is fine as representations, but we could also use formats likeAtom, JSON or even default to XHTML as a sensible middle ground
State machines (defined by links) are important are the engine of theREST workflow
H. Paik (CSE, UNSW) REST Week 7 25 / 61
REST and scalability
Being Statelessness:
Every action happens in isolation: This is a good thing!
In between requests the server knows nothing about youKeeps the interaction protocol simplerMakes recovery, scalability, failover much simpler too
Be work-shy - needs ’server-client’ collaboration:
Provide guard clauses in requests so that servers can determine easilyif there’s any work to be done
If-Modified-Since, If-None-Match/ETag
Web infrastructure uses these to determine if its worth performing therequest
And often it isn’t, so an existing representation can be returned
H. Paik (CSE, UNSW) REST Week 7 26 / 61
REST and scalability
Retrieving a Resource Representation
Request
GET /transactions/debit/1234 HTTP 1.1
Host: bank.example.org
Accept: application/xml
If-None-Match: aabd653b-65d0-74da-bc63-4bca-ba3ef3f50432
Response200 OK
Content-Type: application/xml
Content-Length: ...
Last-Modified: 2010-21-04T15:10:32Z
Etag: abbb4828-93ba-567b-6a33-33d374bcad39
<t:debit xmlns:t="http://bank.example.com">
<t:sourceAccount>12345678</t:sourceAccount>
<t:destAccount>987654321</t:destAccount>
<t:amount>299.00</t:amount>
<t:currency>GBP</t:currency>
</t:debit>
H. Paik (CSE, UNSW) REST Week 7 27 / 61
REST and scalability
Not Retrieving a Resource Representation
Request
GET /transactions/debit/1234 HTTP 1.1
Host: bank.example.org
Accept: application/xml
If-Modified-Since: 2010-21-04T15:00:34Z
Response200 OK
Content-Type: application/xml
Content-Length: ...
Last-Modified: 2010-21-04T15:00:34Z
Client’s representation of the resource is already up-to-date
H. Paik (CSE, UNSW) REST Week 7 28 / 61
REST and scalability
JAX-RS Conditional GET (evaluatePrecondition() and EntityTag())1
@Path("/book/id")
@GET
public Response getBook(@PathParam("id") long id, @Context Request request)
Book myBook = getBookFromDB(id);
EntityTag etag = new EntityTag(Integer.toString(myBook.hashCode()));
ResponseBuilder builder = request.evaluatePreconditions(etag);
// cached resource did change -> serve updated content
if(builder == null)
builder = Response.ok(myBook);
builder.tag(etag);
return builder.build();
Either 200 OK with Book, or 304.
1https://devcenter.heroku.com/articles/jax-rs-http-cachingH. Paik (CSE, UNSW) REST Week 7 29 / 61
REST and scalability
JAX-RS Conditional PUT (evaluatePrecondition() and EntityTag())
@Path("/book/id")
@PUT
@Consumes("application/json")
public Response getBook(@PathParam("id") long id, @Context Request req, Book updatedBk)
Book myBook = getBookFromDB(id);
EntityTag etag = new EntityTag(Integer.toString(myBook.hashCode()));
ResponseBuilder builder = request.evaluatePreconditions(etag);
if(builder != null) // client is not up to date (send back 412)
return builder.build();
updateBookInDB(updatedBk);
builder = Response.noContent();
return builder.build();
If no Etag match, 412 Precondition Failed. Otherwise the update the resource 200 OK (or 204No Content)
H. Paik (CSE, UNSW) REST Week 7 30 / 61
REST and security
REST relies on the elements of the Web for security too ...
Basic security properties ?
HTTPS (SSL)
“Strong” server authentication, confidentiality and integrity protection
The only feasible way to secure against man-in-the-middle attacks
Not cache friendly
Performance vs. security – choice.
H. Paik (CSE, UNSW) REST Week 7 31 / 61
REST and security
Security properties: authentication and authorisation:
Authentication (401 Unauthorized) vs. Authorisation (403 Forbidden):
HTTP Basic (and Digest) Authentication: IETF RFC 2617
Have been around since 1996 (Basic)/1997 (Digest)
Pros:
Respects Web architecture:stateless design (retransmit credentials)headers and status codes are well understood:
Cons:
Basic Auth must be used with SSL/TLS (plaintext password)Only one-way authentication (client to server)
H. Paik (CSE, UNSW) REST Week 7 32 / 61
REST and security
HTTP Basic Authentication Protocol (example):
1 Initial HTTP request to protected resource
GET /index.html HTTP/1.1
Host: example.org
2 Server responds with
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm=‘‘MyRealm’’
3 Client resubmits request
GET /index.html HTTP/1.1
Host: example.org
Authorization: Basic Qm9iCnBhc3N3b3JkCg==
Further requests with same or deeper path can include the additionalAuthorization header preemptively
H. Paik (CSE, UNSW) REST Week 7 33 / 61
REST and security
OAuth (Open Authorisation) Protocol:
Web-focused access delegation protocol
Give other Web-based services access to some of your protected datawithout disclosing your credentials
Simple protocol based on HTTP redirection, cryptographic hashesand digital signatures
Extends HTTP Authentication as the spec allows:
Makes use of the same headers and status codesThese are understood by browsers and programmatic clients
H. Paik (CSE, UNSW) REST Week 7 34 / 61
REST and security
Why OAuth?
H. Paik (CSE, UNSW) REST Week 7 35 / 61
REST and security
OAuth Workflow:
H. Paik (CSE, UNSW) REST Week 7 36 / 61
REST and security
OAuth:
1 Alice (the User) has accounts on both the insurance broker andprovider’s Web sites
2 The insurance broker (Consumer) has registered itself at theinsurance company and has a Consumer Key and Secret
3 Alice logs in to the broker and requests it to obtain her existingpolicies from the provider
4 Broker request to Insurance Provider:
GET /alice/policies HTTP 1.1
Host: insurance.org
5 Insurance provider’s response:
401 Unauthorized
WWW-Authenticate: OAuth realm="http://insurance.org/"
H. Paik (CSE, UNSW) REST Week 7 37 / 61
REST and security
OAuth:
1 Broker requests authorisation token from Provider:
POST /request_token
oauth_consumer_key=abc&oauth_nonce=39kg&oauth_ ...
2 Provider sends authorisation token in response body:
200 Success
oauth_token=xyz&oauth_token_secret=abc
3 Broker redirects Alice to Provider in response to her request:
302 Redirect
Location: http://insurance.org/authorise?oauth_token=
xyz&oauth_callback=http%3A%2F%2Fbroker.org&...
4 Alice logs in to Insurance Provider using her credentials at that site(the Broker never sees these) and authorises the Broker to access herexisting policies for a defined period of time.
H. Paik (CSE, UNSW) REST Week 7 38 / 61
REST and security
OAuth:
1 Insurance Provider redirects Alice to the callback URL:
302 Redirect
Location: http://broker.org/token_ready?oauth_token=xyz2 Broker knows Alice approved, it asks Provider for Access Token:
GET /accesstoken?oauth_consumer_key=abc&oauth_token=xyz
Host: insurance.org3 The Insurance Provider sends back the Access Token:
200 Success
oauth_token=zxcvb4 Broker creates hash or signature using access token, nonce,
timestamp, Consumer Key and Secret (and more):
GET /alice/policies HTTP 1.1
Host: insurance.org
Authorization: OAuth realm=‘‘http://insurance.org/’’,
oauth_signature=‘‘...’’, oauth_consumer_key=‘‘abc’’, .H. Paik (CSE, UNSW) REST Week 7 39 / 61
Web API Design for RESTful services
API - a way for the clients to access your services (or is it a way for you toexpose your servics to the clients ?)
A well-designed API should make iteasy for the clients to understand yourservice without having to “study” theAPI documents in-depth.
self-describing, self-documenting asmuch as possible
the clients are like developers yourself,so probably they would like to have anAPI that is easy to pick up and go
The RESTful service principles actuallygive us a straightforward guideline fordesigning the Web API ...
H. Paik (CSE, UNSW) REST Week 7 40 / 61
Start with URI Design ...
We want to move away from the RPC-style interface design wherelots of ‘operation names’ are used in the URL
e.g., /getCoffeeOrders, /createOrder, /getOrder?id=123
We want to separate the resources from the actions
Use nouns (preferrably plurals) (e.g., orders)
e.g., /orders, /renewal notices,
Could show relationships:
e.g., /orders/{order}/payment, /customers/{customer id}/orders
These resources indicate the type of ‘concepts’ the clients canmanipulate in your service
H. Paik (CSE, UNSW) REST Week 7 41 / 61
Start with URI Design ... continued
Have clear identifiers that leads to individual resources
Mostly you’d use a primary key type like an order Id, an invoice Id ...
Identifiers do not have to be the same as the resource’s internal key(e.g., database id)
e.g., /payments/payment/2015-04-15-by-hpaik, /orders/123
e.g., http://www.smh.com.au/it-pro/security-it/hacker-admits-hijacking-plane-midair-fbi-20150517-gh3fne.html
An id (once decided/generated) should alwyas lead to the sameresource it was created for.
A resource could/should have multiple URLs (i.e., locator) ...
A REST-based service exposes many URIs (end-points)
H. Paik (CSE, UNSW) REST Week 7 42 / 61
Start with URI Design ... continued
Use of Query Strings:
Search:
e.g., /orders?date=2015-04-15, /customers?state=NSW&status=gold
‘select’ queries and relationship navigations
/customers?state=NSW&status=gold
/customers/123/orders vs. /orders?customer=123
/customers/123/shipments
Think: what is the expected resource type in this URI?
Not every exposed URI needs to be in “clean path”, use query stringwhen appropriate
H. Paik (CSE, UNSW) REST Week 7 43 / 61
Start with URI Design ... continued
On the resources’ URIs ... we add ‘actions/verbs’
Resource (URI) GET POST PUT DELETE/coffeeOrders get orders new order batch update ERROR (?)
return a list,status code200
return neworder + newURI, statuscode 201
status code(200, 204)
status code(e.g., 400 -client error)
/coffeeOrders/123 get 123 ERROR (?) update 123 delete 123
return anitem, statuscode 200
return errorstatus code(400 - clienterror)
updateditem, statuscode (200,204)
status code(204, 200)
Note: PUT could also return 201 if the request resulted in a new resource
H. Paik (CSE, UNSW) REST Week 7 44 / 61
Decide How to Use the Status Codes
Using proper status codes, and using them consistently in your responseswill help the client understand the interactions better.
The HTTP specification has a guideline for the codes ..., but at minimum:
Code Description When200 OK all good400 Bad Request you (client) did something wrong500 Internal Error we did something wrong here
And utilise more of these:Code Description When201 Created your request created new re-
sources304 Not Modified cached404, 401, 403 Not Found, Unautho-
rised, Forbiddenfor authentication & authorisa-tion
H. Paik (CSE, UNSW) REST Week 7 45 / 61
Decide on the Design of your Responses
Should support multiple formats (JSON, XML at least) and allow theclient content negotiation to do its jobUse simple objects.
A single result should return a single object.Multiple results should return a collection - wrapped in a container.
/coffeeOrders/123{ “Id”: “123”, “type”: “latte”, “extra shot”: “no”, “payment”: { “date”: “2015-04-15”, “credit card”: “123457” }, “served_by”: “mike”}
/coffeeOrders{ “resultSize”: 25, “results”: [ { “id”: “100”, “type”: “latte”, “extra shot”: “no”, “payment”: { “date”: “2015-04-15”, “credit card”: “22223” }, “served_by”: “sally” }, { … }, ]}
H. Paik (CSE, UNSW) REST Week 7 46 / 61
Taking your API to the Next Level
HATEOAS = Hypermedia As The Engine Of Application State
From Wikipedia: The principle is that a client interacts with anetwork application entirely through hypermedia provideddynamically by application servers. A REST client needs no priorknowledge about how to interact with any particular applicationor server beyond a generic understanding of hypermedia.
Think how people interact with a Web site. No one needs to look up amanual to know how to use a Web site ... Hypermedia (i.e., documentswith links to other thinks) itself serves as a self-explanatory guide for theusers.
The HATEOAS principle aims to realise this in API design.
H. Paik (CSE, UNSW) REST Week 7 47 / 61
SOAP-based service vs. HATEOAS
SOAP-based service is on a single endpoint. The same endpoint receivesrequests for operations. The body of request details which operation torun with what parameters. Think e.g., MarketDataUtilService().
In SOAP, HTTP is merely a carrier of the SOAP messages. HTTP itselfdoesn’t play a big role in the protocol of the servicedesign/implementation/interaction.
In REST, HTTP is at the center of the API. Given that HTTP (Hypertext)is about allowing the users to navigate the site using links, HTTP-basedAPI also should allow the clients to navigate the service using links.
H. Paik (CSE, UNSW) REST Week 7 48 / 61
Not using HATEOAS
Not implementing the links in REST API would look like this:
/coffeeOrders{ “resultSize”: 25, “results”: [ { “id”: 100, “type”: “latte”, }, { “id”: “101”, “type”: “cap”, { … }, ]}
GET /coffeeOrders/100
{ “Id”: “100”, “type”: “latte”, “extra shot”: “no”, “payment”: { “date”: “2015-04-15”, “credit card”: “22223” }, “served_by”: “sally”}
You assume that the client knows how to construct the next requestpath (i.e., combine /coffeeOrders and id:100) - maybe by readingyour API document?
H. Paik (CSE, UNSW) REST Week 7 49 / 61
Using HATEOAS/coffeeOrders/123
{ “Id”: “123”, “type”: “latte”, “extra shot”: “no”, “payment”: { “date”: “2015-04-15”, “credit card”: “123457” }, “served_by”: “mike” “links”: [ { “href”: “/coffeeOrders/123”, “rel”: “self” }, { “href”: “/payments/123”, “rel”: “next” } ]}
/coffeeOrders{ “resultSize”: 25, “links”: [{ “href”: “/coffeeOrders” “rel”: “self” }, { “href”: “/coffeeOrders?page=1”, “rel”: “alternative” } { “href”: “/coffeeOrders?page=2”, “rel”: “nextPage” } ], “results”: [ { “id”: “100”, “type”: “latte”, “links”: [ { “href”: “/coffeeOrders/100”, “rel”: “details” }] }, { … }, ]} H. Paik (CSE, UNSW) REST Week 7 50 / 61
Using HATEOAS
Use links to:
help the clients use the API (self-describing as possible)
navigate paging (prev, next)help create new/related itemsallow retrieving associations (i.e., relationships)hint at possible actions (update, delete)
evolve your workflow (e.g., adding extra step in a workflow = addinga new link)
Standard link relations:http://www.iana.org/assignments/link-relations/link-relations.xhtml
Although the principle is well-understood, how HATEOAS links areimplemented (i.e., how the links appear in the responses) is different fromone implementation to another ...
H. Paik (CSE, UNSW) REST Week 7 51 / 61
The Richardson Maturity Model
Leonard Richardson: can we measure to what level your service isRESTful?
Level 0: One URI (single endpoint) exposed, requests containoperation details
Level 1: Expose resource URIs - individual URIs for each resource.Requests could still contain some operation details
Level 2: HTTP Methods - use the standard HTTP methods, statuscodes with the resource URIs,
Level 3: HATEOAS - self-documenting responses, responses includelinks that the client can use
in picture: https://technobeans.files.wordpress.com/2012/09/richardson-maturity-model.png
H. Paik (CSE, UNSW) REST Week 7 52 / 61
Positive aspects of REST
Faster response time (caching)
Reduced server load (caching)
Improved server scalability and easier load-balancing (no session state)
Client software can be reused (uniform interface)
Can be implemented with any server-side technology
HTTP client libraries are widespread
The ”web” in ”Web services” is for real!
H. Paik (CSE, UNSW) REST Week 7 53 / 61
Negative aspects of REST
No interface description language like IDL or WSDL
need to “read” the doc to understand how to interact ...
e.g., typical examples ... Facebook, Twitter, Google Search API
Low tooling support for automation (but frameworks are comingalong)
REST purist vs. pragmatic developers - no right/wrong answer ??
H. Paik (CSE, UNSW) REST Week 7 54 / 61
When can I use REST?
For Web Services
build your web service using the REST style
alternative to some of WS-*, not a replacement for WS-*
Clients interfacing to public REST APIs
e.g. Amazon S3 REST API, Google Data APIs
Many other public APIs have a REST like interface
Often combined with interactive Web clients
client sends AJAX requests to a REST interface using a JavaScriptlibrary e.g. jQuery ... the responses (JSON, XML etc) are thenmanipulated and displayed on the client
H. Paik (CSE, UNSW) REST Week 7 55 / 61
REST + SOAP
Wrapping REST request/response with SOAP envelopes:
For example, the following request
http://127.0.0.1:8080/axis2/services/version/getVersion
will be converted to the following SOAP Message for processing by Axis2
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<axis2:getVersion xmlns:axis2="http://ws.apache.org/goGetWith... />
</soapenv:Body>
</soapenv:Envelope>
http://ws.apache.org/axis2/0_94/rest-ws.html
H. Paik (CSE, UNSW) REST Week 7 56 / 61
REST + SOAP
GET http://www.parts-depot.com/parts/00345 HTTP/1.1
<?xml version="1.0"?>
...
<soap:Envelope ...>
<soap:Body>
<PartDetails xmlns=" ...>
<Part-ID>00345</Part-ID>
<Name>Widget-A</Name>
<Description>This part is used within the frap assembly</Description>
<Spec xlink:href="http://www.parts-depot.com/parts/00345/spec"/>
<UnitCost currency="USD">0.10</UnitCost>
<Quantity>10</Quantity>
<Order href="http://.../Orders/" />
</PartDetails>
</soap:Body>
</soap:Envelope>
H. Paik (CSE, UNSW) REST Week 7 57 / 61
REST + SOAP
Placing an order:
H. Paik (CSE, UNSW) REST Week 7 58 / 61
REST vs SOAP - Technology
User-driven interaction via richWeb client application
Few operations on manyresources
URI - consistent naming forresources
focus on Scalability andperformance
Distributed hypermedia systems
Composition= mashups
Orchestrated, reliableevent/message flows
Many operations (WSDLinterface) on few resources
Lack of standard namingmechanism
focus on design of integratedenterprise applications
composition = businessprocesses
H. Paik (CSE, UNSW) REST Week 7 59 / 61
REST vs SOAP - ProtocolREST vs SOAP - ProtocolXML in – XML out (with POST)URI in – XML out (with GET)
SOAP in – SOAP out (with POST)
Self-Describing” XML
HTTP only
Strong Typing (XML Schema)
“Transport independent”HTTP only
HTTP/SSL is enough – no need for more standards
Transport independentHeterogeneity in QoS needs.Different protocols may be used
HTTP is an application protocolSynchronous
HTTP as a transport protocolSynchronous and Asynchronous
Do-it-yourself when it comes to “reliable message delivery”, “distributed transactions”
Foundation for the whole WS* advanced protocol stack
45
p
REST vs. SOAP Design MethodologyIdentify resources to be exposed as services (e.g., book catalog, purchase order)
List what are the service operations (the “verbs”) into the service’s WSDL documentp )
Define “nice” URLs to address them
Define a data model for the content of the messages exchanged by the service (XML
Distinguish read-only and side-effects free resources (GET) from modifiable resources (POST, PUT, DELETE)
e c a ged by e se ce (Schema data types)
Choose an appropriate transport protocol to bind the operationPUT, DELETE)
Relationships (e.g., containment, reference) between resources correspond to hyperlinks that can
protocol to bind the operationmessages and define the corresponding QoS, security, transactional policies
correspond to hyperlinks that canbe followed to get more details
Implement and deploy on Web server
Implement and deploy on the Web service container (note the corresponding SOAP engine end-point)
46
server
Is it really one or the other?
Each have their advantages and disadvantages, and so their use casesand so their use cases
Choosing the right one is an architectural decision that should be made based on the application
SOAP-based Web services can be RESTfulSOAP 1.2 is not restricted to use over HTTP POST
SOAP 1 2 HTTP binding supports HTTP GETSOAP 1.2 HTTP binding supports HTTP GET
Response can use SOAP extensions, e.g. encryption of part of the message
One can design a system made of resources and use SOAPOne can design a system made of resources, and use SOAPwith HTTP GET and POST where appropriate
Web services technologies can be useful in the context of non SOAP based REST ser ices
47
non-SOAP-based REST services
RESTful Web Services
H. Paik (CSE, UNSW) REST Week 7 60 / 61
REST vs. SOAP Design MethodologyREST vs SOAP - Protocol
XML in – XML out (with POST)URI in – XML out (with GET)
SOAP in – SOAP out (with POST)
Self-Describing” XML
HTTP only
Strong Typing (XML Schema)
“Transport independent”HTTP only
HTTP/SSL is enough – no need for more standards
Transport independentHeterogeneity in QoS needs.Different protocols may be used
HTTP is an application protocolSynchronous
HTTP as a transport protocolSynchronous and Asynchronous
Do-it-yourself when it comes to “reliable message delivery”, “distributed transactions”
Foundation for the whole WS* advanced protocol stack
45
p
REST vs. SOAP Design MethodologyIdentify resources to be exposed as services (e.g., book catalog, purchase order)
List what are the service operations (the “verbs”) into the service’s WSDL documentp )
Define “nice” URLs to address them
Define a data model for the content of the messages exchanged by the service (XML
Distinguish read-only and side-effects free resources (GET) from modifiable resources (POST, PUT, DELETE)
e c a ged by e se ce (Schema data types)
Choose an appropriate transport protocol to bind the operationPUT, DELETE)
Relationships (e.g., containment, reference) between resources correspond to hyperlinks that can
protocol to bind the operationmessages and define the corresponding QoS, security, transactional policies
correspond to hyperlinks that canbe followed to get more details
Implement and deploy on Web server
Implement and deploy on the Web service container (note the corresponding SOAP engine end-point)
46
server
Is it really one or the other?
Each have their advantages and disadvantages, and so their use casesand so their use cases
Choosing the right one is an architectural decision that should be made based on the application
SOAP-based Web services can be RESTfulSOAP 1.2 is not restricted to use over HTTP POST
SOAP 1 2 HTTP binding supports HTTP GETSOAP 1.2 HTTP binding supports HTTP GET
Response can use SOAP extensions, e.g. encryption of part of the message
One can design a system made of resources and use SOAPOne can design a system made of resources, and use SOAPwith HTTP GET and POST where appropriate
Web services technologies can be useful in the context of non SOAP based REST ser ices
47
non-SOAP-based REST services
RESTful Web Services
H. Paik (CSE, UNSW) REST Week 7 61 / 61