When to use REST based web services?

REST expose a much simpler interface than SOAP, with some limitations. Development with REST is easier and quicker and this is the reason why most famous web APIs are REST-based.
 
The limitations are related to the protocol: with REST you are bound to HTTP. So it is difficult to handle different transports like MQ or JMS. So if you are designing an application to be used exclusively on the web, REST could be the option. If you are designing a SOA for an Enterprise, that needs to interconnect to multiple systems using multiple transport/channels and having sophisticated transactions to be modeled with BPMs, then it is better to go with SOAP.
Note than you are going to pay SOAP’s flexibility with development complexity: SOAP interfaces are described by the WSDL standard which looks really complicated and is not supposed to be read by humans.

RESTful applications simply rely on the built-in HTTP security (the HTTPS protocol), with SOAP you can have more sophisticated choices, like WS-Security that lets you encrypt only portions of the messages and moves the security handling from the transport layer to the message layer.

REST is younger than SOAP, so it is not as well supported by commercial products (both BPM and ESB products). However new versions of the major ESBs support REST (ex mule, openesb).

RESTful services do not have a strict describtor, they tried to define something simmilar to WSDL, it’s called WADL (https://wadl.dev.java.net/). The WADL is currently not a common standard the adoption is very low and mostly not wanted for RESTful services.

Even for ESB’s most of the vendors where lacking the support some month ago. But now nearly each big ESB vendor (commercial or open source) supports the RESTful protocol. From the usage of an ESB it is currently not a problem to run RESTful services.

If you plan to run a very big deployment with many data interfaces, you will get great benefits using RESTful Services. REST is based 100% on the HTTP rfc (http://www.w3.org/Protocols/rfc2616/rfc2616.html). Many of the RESTful Interface which you see currently on the internet do not fully support HTTP specification, the result is that they could not benefit from it in terms of performance, caching, content negotiation and security. 
One great reason is to use RESTful interfaces is it can easily support different content-types/mime-types. First you think about, vendor specific XML with a xsd definition, later you would like to support AJAX Mashups and even later you think about to support text formats, reports in PDF, and so on. This is very easy to implement with REST because you query always with the same data query but the requested content type is just different.
Another reason why people are using RESTful interfaces is to be scalable like the web (www) and google. This is possible when you are using plain and simple HTTP protocol. You have support from so many standard product like web proxy caches (like SQUID) or other to scale your application a very low effort. For Social Communities you have have now a new Standard for RESTful Service Security. It is called Oauth (http://oauth.net/) which makes authentication over HTTP very easy.

Some other examples where RESTFul Services are dominant:
Amazon AWS: E.g. they offer Services for Storage (S3) and they have SOAP and REST interfaces but over 90% of the clients are using REST
Google Maps is using RESTful uris to provide cachable map tiles
yahoo API’s are mostly build with RESTful interfaces
RESTful Services are very dominant in lighweight web 2.0 API’s for Mashups like OpenSocial
API.

REST design is good for the database driven applications and when client wants quick integration.

Some Web Services Best Practices

1. Start designing web service with WSDL and schema i.e., follow Top-Down approach.If already have classes or EJBs that need to be exposed as web services,then bottom-up approach is the only choice and the resulting WSDL will be generated by Web Services toolkit. It is easy to design a Web Service from exisiting classes but then it offers less flexibility when reuse of definitions are desired. Also, the WSDL will contain a format that is specific to the web services toolkit being used and it will not be possible to add extra information or annotations in the WSDL by including the documentation element of WSDL.

2. In RPC style of web services, the job of marshalling and unmarshalling is performed by SOAP engine. This may lead to significant performance degradations if complex operations are involved. However, RPC style web services are better suited for implementing fine-grained functionalities.

3. Implemention of Document style web services is complex and time-consuming. Document-style Web Services can handle large documents without any performance trade-offs. If coarse-grained functionality is required then Document style web service is the right choice. These are also suitable when asychronous operations are involved.

4. Using “encoding” requires both sides to have prior knowledge of the encoding style. It is the responsibility of SOAP engine to perform encoding adn decoding, which is an overhead. It is not preferred for complex data structures.

5. When use is set to “literal”, XML schema directly defines the data types. It is preferred when complex and custom data types are involved and better performance is desired.

6. To decide what style and use from available choices: RPC-encoded, RPC-literal, Document-literal and Document-encoded, should be used, following link that gives detailed explanation can be referred:
 
 http://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/ 

7. SOAP with attachment or SwA is useful for documents that conforms to schema in languages not supported by web service end point.Sending information as attachments rather than in SOAP body results in smaller body and faster processing. However, writing a SOAP handler can be tedious. Care should be taken while using Message Queues to transmit the message as the message queue capacity may be less and the message may require chopping.

8. Though services can maintain state whenever there is a high volume of related requests and responses and responses need to sent in pieces. Maintaning state is not desired when trying to implement Service Oriented Architecture though.

9. As XML is verbose and takes up considerable size, solutions like binary-XML can be used to zip or compress the message. Both client and server should be able to access the compression technique.

10. Use message oriented middleware (MOM) to handle asynchronous communication and where sensitive data are transmitted. This is a good choice to achieve Reliable Messaging.

11. Data binding specific to a SOAP engine is switched off in case of Document –literal style web service. Custom binding mechanisms like castor, xmlbeans, JAXB, JaxMe can be used by applications to offload the job of marshalling and unmarshalling from SOAP engine and handle custom data types.

12. SOAP engines use parsing mechanisms internally. Parsing is an overhead and it can lead to performance issues. Axis 2.0 uses a new mechanism called AXIOM (AXis Object Model) which is a StAX-based, XML Infoset compliant object model which supports on-demand building of the object tree.

13. Use WS-Security for transmitting sensitive data. However, always secure part of message and not the entire message. Usage of HTTPS for transport level security is desired. SAML should be used for identity management.

14. Use a test harness tool like SOAPUI for testing the web services client by creating mock or simulated web services. Use TCP/IP monitor for tracing the SOAP messages.

15. XML security gateways and proxies can be used to prevent Denial of Service (DoS) attacks.

16. ESB or Enterprise Service Bus can be used when there is lot of integrating logic and activities like message routing, validation, enrichment, transformation, monitoring, logging and event management need to be deferred. ESB is the underlying infrastructure for implementing SOA. Canonical applications can be exposed as web services using adapters and current world ESBs are equipped with adapters for such applications.

17. Use UDDI-based registry to maintain a system of record, increase visibility of services and manage lifecycle and versioning of services.

18. Use a workflow language like BPEL to orchestrate services and provide Business Process Management (BPM). This is important for facilitating agility and hiding technical complexities.

19. Check if your web service is WS-I basic profile compliant and conforming to all the rules. http://www.ws-i.org/deliverables/workinggroup.aspx?wg=basicprofile

Parse WSDL effectively

As a WSDL’s constituents are well-defined already, it is feasible to use a parser that can get the elements of the WSDL using APIs that are already defined. This will minimize complexity in the code and will help in achieving better performance.

 

Oracle WSDL parser is one such option.

 

It is only needed to import the necessary classes as the APIs are already defined and packaged with wsdl.jar.

 

//importing the necessary classes from library

import oracle.wsdl.WSDLDocument;

import oracle.wsdl.internal.Binding;

import oracle.wsdl.internal.Definitions;

import oracle.wsdl.internal.Documentation;

import oracle.wsdl.internal.Import;

import oracle.wsdl.internal.Message;

import oracle.wsdl.internal.PortType;

…….

 

 

WSDLDocument wsdldoc = new WSDLDocument(wsdl_url);

//getting definition element

Definitions definition = wsdldoc.getDefinitions();

//getting service element

Map servicesMap = definition.getServices();

//getting binding element

Map bindingsMap = definition.getBindings();

//getting PortType element

Map ptypesMap = definition.getPortTypes();

//getting message element

Map messagesMap = definition.getMessages();

//getting import details

Map importsMap = definition.getImports();

//getting documentation details

Documentation docs = definition.getDocumentation();

 

 

As there can be multiple elements, an “iterator” can be used to parse an individual element.

For Example:

 

Iterator iterator = servicesMap.entrySet().iterator();

        while (iterator.hasNext()) {

            Map.Entry me = (Map.Entry) iterator.next();

            …….

        }

 

The above code fragments keep things fairly simple while processing a WSDL.

 

Apache Woden

 

Woden provides Java class library for reading, manipulating, creating and writing WSDL documents.

 

Woden’s DOM-based XML parsing depends on Apache Xerces 2.7.1. Its XML Schema support it depends on the schema parser and object model implemented by the Apache Web Services Commons (ws-commons) XmlSchema project.

 

//importing necessary classes from woden jars

import org.apache.woden.WSDLException;

import org.apache.woden.WSDLFactory;

import org.apache.woden.WSDLReader;

import org.apache.woden.wsdl20.Binding;

import org.apache.woden.wsdl20.Description;

import org.apache.woden.wsdl20.Interface;

import org.apache.woden.wsdl20.Service;

….

 

  

 

WSDLFactory factory = WSDLFactory.newInstance();

WSDLReader reader = factory.newWSDLReader();

reader.setFeature(WSDLReader.FEATURE_VALIDATION, true);

String wsdlurl = “C://axis2-1.4.1//newwsdl.wsdl”;

 

//reading the WSDL Document

DescriptionElement descElem = (DescriptionElement) reader.readWSDL(wsdlurl);

Description descComp = descElem.toComponent();

 

//getting Interface, Binding and Service elements

InterfaceElement[] interfaces = descElem.getInterfaceElements();

BindingElement[] bindings = descElem.getBindingElements();

ServiceElement[] services = descElem.getServiceElements();

  

 

Complete details about usage and extensibility of woden are available at:

 

http://ws.apache.org/woden/userguide.html

 

JWSDL:

 

 

JWSDL is another option that is intended for use by developers of Web services tools and others who need to utilize WSDL documents in Java.

JWSDL is designed to allow users to read, modify, write, create and re-organize WSDL documents in memory. JWSDL is not designed to validate WSDL documents beyond syntactic validity. One use of JWSDL is to develop a tool that validates WSDL semantically.

JWSDL is designed for use in WSDL editors and tools where a partial, incomplete or incorrect WSDL document may require representation.

 

Details of JWSDL can be obtained by accessing the following link:

 

http://wsdl4j.sourceforge.net/downloads/JSR110_proposed_final_draft.pdf

What XML parser to use?

XML, being the lingua franca of web services, has found its use in many applications mostly because of its platform agnostic feature. Applications using XML and XML-based artifacts like SOAP, WSDL etc. tremendously require traversal, customization and transformation of these artifacts to suit its needs. This is the reason why we see parsing and binding (marshalling and unmarshalling) of XML documents at various critical points in an application. One important thing to note is that XML is verbose and leads to various performance issues when processed, especially in complex environments. Over the years, we have seen use of DOM (Document Object Model) and SAX (Simple API for XML) parsers but these parsers have their own limitations and require trade-offs in some situations. For example,  

DOM requires in-memory representation of the XML document, which exerts unnecessary pressure on system resources and is thus considered impractical for large documents. Also, DOM APIs introduces complexity while processing XML nodes.

Other alternatives or parsers that use tree-based APIs are dom4j, JDOM and XOM. While dom4j document object model is fast and memory-efficient and offers great extensibility, JDOM is mostly known for its ease of use. The XOM document object model protects users from common mistakes in the use of XML, while offering good performance and memory efficiency. 

SAX, on the other hand, is inappropriate when reordering or cross-referencing of XML nodes is desired. 

WoodStox is an XML processor that combines the best of both the worlds. In other words, it is easy to use or convenient like DOM and efficient like SAX. It is an open source implementation of StAX pull parser standard. It, however, encounters performance issues like Xerces2, the Apache Implementation of the W3C document object model standard, when dealing with small documents, for eg. SOAP. 

To improve the performance of such widely-used XML parsers, Apache introduced a new parser. This new parser, AXIs Object Model (AXIOM), is considered not just another object model but a very useful and performance enhancing parser for CPU and Memory intensive applications. AXIOM tries to achieve its objective of being a memory-efficient parser by deferring creation of XML tree when not required. AXIOM is StAX (Streaming Api for XML) based object model and it implements “pull-parsing” methodology, unlike SAX and DOM. It also has built in support for XML Optimized Packaging (XOP) and MTOM, the combination of which allows XML to carry binary data efficiently and in a transparent manner. Another important feature supported by AXIOM is that it provides APIs to parse SOAP (Simple Object Access Protocol) documents effectively. When the APIs are already defined, complexity can be easily avoided and performance overhead can be easily tackled. Apache’s SOAP engine Axis2, thus, has provision for AXIOM. AXIOM’s ability to support various binding mechanisms helps it optimize the marshalling and unmarshalling of XML fragments and hence, results in improved performance.

 

While AXIOM has pre-defined APIs for parsing a SOAP message, it should also be possible to define APIs that can extract elements from a WSDL (Web Services Description Language) file.

 

Preserve white spaces in a SOAP message

Sometimes, the business requirement mandates that a SOAP request/response should maintain leading or trailing spaces that are present in a variable. By default, this does not happen. For example, you may expect ” ABC” or “ABC “, but you get “ABC”. The spaces are removed. Also, you may encounter issues if you use a binding mechanism like JAXB to marshal/ unmarshal xml fragments.  This requires modifying the default marshalling or unmarshalling behavior. This is how you can still maintain any whitespaces:

Before marshalling call

marshaller.setPropertyMarshaller.JAXB_ENCODING, “UTF-8″)

 which informs MarshallerImpl#createWriter(…) to create a UTF8XmlOutput instead of SAXOutput. 

UTF8XmlOutput escapes line-break into “ ”, which will be preserved when unmarshalling is performed by any xml parser.

RPC-style vs Document-Style Web Service

There has been lot of confusion on which style of web service is used but It is always recommended to use a Document-style webservice to realize SOA.

RPC style web service:
These web services are easier to create and are usually synchronous in nature.
The responsibility of marshalling and de marshalling lays with SOAP engine, This leads to significant performance degradations when message passed to an operation is large or complex.
Since large sized messages lead to performance degradation in RPC style web service, they are not suitable for implementing coarse grained functionality requiring information messages having more number of fields.
However fine grained functionalities is better implemented by RPC style web services.
Document style web service:
Document style web services are more time consuming to create, as it is the onus of the service to create the required objects from XML document.
These web services can consume large sized documents without any significant drop in performance as there are no overheads of marshalling and de marshalling associated with SOAP engine.
Document style web services are ideal for representing coarse rained functionality as a single large sized  document can be used to transfer information required to implement a business functionality.
Document style web service are primarily used for implementing asynchronous service.

RPC encoded web services are easiest  create but offers least control in terms of usage of custom data types, validation and interoperability.
RPC encoded web service are slower in performance because of added overheads of marshalling and un marshalling.
Document literal web services are harder to create but scores higher in all the above metrics and this is one of the reasons WS –I basic profile encourages the usage of document literal web services.

Document style web services are better suited for defining custom data types as they are not constrained by the usage of a particular encoding style. Document –literal web services offers the best performance and RPC –encoded web services offers the least performance as in document-literal web service overheads of marshalling and un marshalling no longer lies with SOAP engine. In a document –literal web service alternative techniques such as  SAX based parsing or custom data binding tool like XML beans, castor can be used.In case SOAP engine does not maintain state a document –literal web service can be used to carry state related data in the document. While using RPC –encoded web service often platform specific data structures are exposed in WSDL, which might not be supported by other platforms.