ICSOC 2008 Summer School session on REST-based Services · Drink Made Drink Released Lookup Next Order Make Drink Take Payment Lookup Next Order the barista loops around looking for

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

http://www.xfront.com/REST-Web-Services.html

http://www.infoq.com/articles/webber-rest-workflow

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.


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


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)


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.


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


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-Length: ...



<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$



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


!!I&)-5()&$200 OK

Allow: GET, PUT L.&<G$K$0,($

:-@,1&$#/$5'@&'8$

E5'$(5<$



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


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.&'<")&=$



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&$



PUT and its RESPONSE

Amending an Order: On the Wire

•! Request PUT /order?1234 HTTP 1.1



Content-Length: ...



<additions>shot</additions>

<link rel="payment" href="https://starbucks.example.org/payment/order?1234"


</order>

•! Response 200 OK

Location: http://starbucks.example.org/order?1234


Content-Length: ...






</order>



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 ...


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


...

!!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


!!I&)-5()&$Allow: GET



Customer: Order update successful, what now ...?

Order Confirmation: On the Wire

•! Request GET /order?1234 HTTP 1.1



Content-Length: ...


Location: http://starbucks.example.org/order?1234


Content-Length: ...






</order>

C'&$1.&/$1'/"(7$15$1&44$#&$

)5#&1."(7$<"1.$./-&'#&@",W$



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[$



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


!!I&)-5()&$Allow: GET, PUT



Order Payment: On the Wire

•! Request PUT /payment/order?1234 HTTP 1.1



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-Length: ...

<payment xmlns="urn:starbucks">

<cardNo>123456789</cardNo>

<expires>07/07</expires>

<name>John Citizen</name>

<amount>4.00</amount>

</payment>



Check that you’ve paid

•! Request GET /order?1234 HTTP 1.1



Content-Length: ...



Content-Length: ...




</order>

T/$OCLKP$.,)$0.,(7&@8$

9&0,:)&$K;?&$-,"@$&(5:7.$

(5<$



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):


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.


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


Finally drink your coffee...

35:'0&_$.^-_``"#,7&)D9:)"(&))<&&6D05#`))`cd`c]`15-e9',(@)`"#,7&`)1,'9:06)DF-7$



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 !


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


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



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



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-Length: ...

Last-Modified: 2010-21-04T15:00:34Z

Client’s representation of the resource is already up-to-date



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


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)


updateBookInDB(updatedBk);

builder = Response.noContent();


If no Etag match, 412 Precondition Failed. Otherwise the update the resource 200 OK (or 204No Content)


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.


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)


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


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


REST and security

Why OAuth?


REST and security

OAuth Workflow:


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


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.


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 ...


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


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)



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



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


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


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” }, { … }, ]}


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.


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.


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?


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 ...


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

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!


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 ??


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


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


http://ws.apache.org/axis2/0_94/rest-ws.html

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>


REST + SOAP

Placing an order:


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


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


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


ICSOC 2008 Summer School session on REST-based Services · Drink Made Drink Released Lookup Next Order Make Drink Take Payment Lookup Next Order the barista loops around looking for

Documents