REST in Peace with Web services

Eran Chinthaka (chinthaka@apache.org)

Samisa Abeysinghe (samisa@apache.org)

WSO2 Inc.

Who We AreEran Chinthaka

• Member – Apache Software Foundation• Lead Developer – Apache Axiom, Axis2,

Synapse, Tungsten• W3C WS-Addressing working group

member• Senior Software Engineer- WSO2 Inc.

Samisa Abeysinghe• Member – Apache Software Foundation• Lead Developer Apache Axis2/C and Axis

C++• Software Architect – WSO2 Inc.

Agenda• What is REST and Web services?• SOAP vs. REST• How WSDL 2.0 enables REST?• How can it be implemented? – Axis2

Architecture• Getting your feet wet with 'code'

4

What is REST ...?• REpresentational State Transfer • “Representational State Transfer is intended to

evoke an image of how a well-designed Web application behaves: a network of web pages (a virtual state-machine), where the user progresses through an application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for

their use.” - Roy T. Fielding• Architectural Style of network

systems

5

Why is it called REST ?

• Web comprised of resources• Accessing

http://www.wso2.net/products/tungsten

• Representation of the resource is accessed

• Places client application in a state• Client application changes

(transfers)

6

REST, a standard?

• An architectural style• Not a standard• But uses standards

• http• url• xml/html/gif/jpeg, etc – media types• text/xml, text/html, etc – MIME types

7

SOAP

• SOAP is a messaging protocol• has three parts

<envelope><Header/><Body/>

</envelope>

• Body is for payload• Header is for QoS

• Addressing, Security, RM

8

REST vs. SOAP● REST

– Fixed interface ● URI for GET case● XML for POST case

– Mostly HTTP Transport

– Lighter bandwidth

– QoS support – based on transport

– Suited for lightweight scenarios

● SOAP– Flexible interface

● POST with SOAP envelope

– Transport agnostic

– Comparatively higher bandwidth

– Wide array of message level QoS options – WS-*

– Suited for heavyweight scenarios

9

“REST”?• Our objectives

• Support “plain old XML” interaction with services over POST

• Support HTTP GET bindings for services

• Non-objectives:• Support all of REST

10

How WSDL 2.0 Enabled the REST + WS “Marriage”

• WSDL 2.0 HTTP binding enables services to be used with GET and POST

• Specify how to take (certain styles of) an XML Schema and formulate a GET/POST request out of it

11

WSDL 2.0 Rules for HTTP Binding

• binding type should be “http://www.w3.org/2006/01/wsdl/http”

• Formulating a HTTP message, contents of payload defined in MessageReference or InterfaceFault

• Schema should adhere to IRI style

12

IRI Style

• An element style defined on the schema of the payload

• Rules : • The content model of this element is defined using a

complex type that contains a sequence from XML Schema.

• The sequence MUST only contain elements. It MUST NOT contain other structures such as xs:choice.

• The sequence MUST contain only local element children. These child elements MAY contain the nillable attribute.

• The localPart of the element's QName MUST be the same

as the Interface Operation component's {name}.

13

IRI Style

• Rules : • The complex type that defines the body of the element or

its children elements MUST NOT contain any attributes.

• If the children elements of the sequence are defined using an XML Schema type, they MUST derive from xs:simpleType, and MUST NOT be of the type or derive from xs:QName, xs:NOTATION, xs:hexBinary or xs:base64Binary.

14

Input and Output Serialization Formats

• Default :

Default Input Serialization Default OutputGETPOSTPUT

HTTPMethodapplication/x-www-form-urlencoded application/xmlapplication/xml application/xmlapplication/xml application/xml

15

Input and Output Serialization Formats

16

Input and Output Serialization Formats

• Allowed Formats :

source :

17

Operation Styles Required

source :

18

Implementing in Apache Axis2

• Apache Axis2/Java

• Apache Axis2/C

• Understand REST implementation --> Understand Axis2 Architecture ....

19

Axis2 – Messaging Engine

• Piped view

20

Axis2 – The Big Picture

Application

Transport

Ph

as

e Z

Ph

as

e Y

Ph

as

e X

XMLMessage

Engine

Message

Receiver

MessageContext

21

Axis2 – Inside Message Context

MessageContext

Property Bag

someObject“property2”

Boolean.TRUE“property1”

ExecutionChain

<soap:Envelope> <soap:Body> <myNS:OrderSushi> ... </myNS:OrderSushi> </soap:Body></soap:Envelope>

Message

• Pointers to OperationContext, ServiceContext, ConfigurationContext

• Other fields

Handlers

22

Axis2 - Dispatching

• Finding the correct service and operation a message is destined to.

• Dispatchers• RequestURIBasedDispatcher• AddressingBasedDispatcher• SOAPActionBasedDispatcher• SOAPMessageBodyBasedDispatcher

23

Axis2 – Content Type Handling

• Builders for different content types• StAXOMBuilder• StAXSOAPModelBuilder• MTOMSOAPBuilder

24

Marrying REST with Axis2 – Receiving REST Requests

• Axis2 engine needs SOAPEnvelope to process a message.

• On receiving the message --> dispatch

• Get schema and check the message, construct SOAPBody in accordance with the schema

• Create SOAPEnvelope and pass it to the engine

25

Marrying REST with Axis2 – Receiving REST Requests

• Engine doesn't know about REST, except a flag

• Works with GET and POST with any content type

26

Marrying REST with Axis2 – Sending REST Requests

• Client API is the same for SOAP and REST requests, except• a flag to notify its REST• HTTP method (optional)• content type (optional)

• TransportSender serializes the proper way

27

Getting Your Feet Wet ...• Sending a SOAP Request ...

• Sending REST Request (minimal config)

Options options = new Options();options.setTo(new EndpointReference(toEpr));

ServiceClient sender = new ServiceClient();sender.setOptions(options);OMElement result = sender.sendReceive(getPayload());

Options options = new Options();options.setTo(new EndpointReference(toEpr));

options.setProperty(Constants.Configuration.ENABLE_REST , Constants.VALUE_TRUE); ServiceClient sender = new ServiceClient();sender.setOptions(options);OMElement result = sender.sendReceive(getPayload());

28

More Control • Sending REST Request (optional

configuration)• Setting content type

• Available content types• MEDIA_TYPE_X_WWW_FORM - application/x-

www-form-urlencoded• MEDIA_TYPE_TEXT_XML - text/xml• MEDIA_TYPE_MULTIPART_RELATED -

multipart/related• MEDIA_TYPE_APPLICATION_XML -

application/xml

options.setProperty(Constants.Configuration.CONTENT_TYPE, contentType);

29

More Control .... • Sending REST Request (optional

configuration)• Setting HTTP Method

• Available Web Methods• HTTP_METHOD_GET • HTTP_METHOD_POST (Default)

options.setProperty(Constants.Configuration.HTTP_METHOD, webMethod);

30

REST Configuration in Axis2 – Server Side

• Any service that abides with WSDL 2.0 HTTP Binding is REST enabled.

31

I'm a C fan, Can I also “REST” ?

YES !!!

32

Getting Your Feet Wet (again) with C

• Sending a SOAP Request ...endpoint_ref = axis2_endpoint_ref_create(env, address);

options = axis2_options_create(env);

AXIS2_OPTIONS_SET_TO(options, env, endpoint_ref);

svc_client = axis2_svc_client_create(env, client_home);

AXIS2_SVC_CLIENT_SET_OPTIONS(svc_client, env, options);

ret_node = AXIS2_SVC_CLIENT_SEND_RECEIVE(svc_client, env, get_payload(env));

33

Getting Your Feet Wet (again) with C ...

● Enabling REST at the client sideAXIS2_OPTIONS_SET_PROPERTY(options, env, AXIS2_ENABLE_REST,

AXIS2_VALUE_TRUE);

34

Getting Your Feet Wet ...• Sending REST Request ...

endpoint_ref = axis2_endpoint_ref_create(env, address);

options = axis2_options_create(env);

AXIS2_OPTIONS_SET_TO(options, env, endpoint_ref);

AXIS2_OPTIONS_SET_PROPERTY(options, env, AXIS2_ENABLE_REST, AXIS2_VALUE_TRUE);

svc_client = axis2_svc_client_create(env, client_home);

AXIS2_SVC_CLIENT_SET_OPTIONS(svc_client, env, options);

ret_node = AXIS2_SVC_CLIENT_SEND_RECEIVE(svc_client, env, get_payload(env));

35

More Control

AXIS2_OPTIONS_SET_PROPERTY(options, env, AXIS2_CONTENT_TYPE, content_type);

AXIS2_OPTIONS_SET_PROPERTY(options, env, AXIS2_HTTP_METHOD, web_method);

36

Summary

• What is REST and Web services ?• SOAP vs. REST• How WSDL 2.0 enables REST• How can it be implemented – Axis2

Architecture• Getting your feet wet with code

37

Questions ... ?

Download presentation from

http://people.apache.org/~chinthaka/presentations/ApacheConEU2006/RESTInPeaceWithWS.ppt

38

Thank You .