Best practices 2 – Web Services

This is the second post in our SOA and BPM best practices series. This blog is about Web Services and provides a mix of general tips and more specific tips for Web Services that are implemented using Java and JEE. You can find the first blog in this series here.

Approach. Decide upfront, based on the requirements and constraints, what approach for Web Service development best suits your situation: top-down or contract first, bottom-up, or meet-in-the middle.

• Top-down or contract first. The starting point here is the contract of the Web Service: its WSDL. You either design it or it is provided as a 'given fact'. From the WSDL you generate the implementation. If the contract frequently changes, regeneration of the code can cause difficulties since the implementation is overridden. If you use this method, make sure you don’t change the generated artifacts.
• Bottom-up or implementation first. The starting point is the implementation; all Web Service artifacts "such as its WSDL’s" are generated. This is a fast approach when you want to expose existing components as Web Service. However, you need to be careful because you have limited control over the generated Web Service artifacts and it is therefore easy to break an interface if the Web Service is regenerated.
• Meet-in-the-middle approach. Here you define both contract and implementation yourself and later on create the glue between them. In case of Java you can use JAX-WS and JAXB APIs and code to create this glue. This is a very flexible approach: you can change both the WSDL and the implementation. It requires more work in the beginning, but is easier to change later on.

Compliance. A Web Service that isn’t standards-compliant is less (re)usable. Make sure your Web Service is compliant to the WS-* standards by using the WS-I profiles (Web Services Interoperability Organization).

Exposing operations. Don’t expose all methods as Web Service operations by default when using a bottom-up or meet-in-the-middle approach. Only expose those methods that are actually needed by service consumers. This promotes encapsulation and prevents access to ‘internal’ methods.

Products. Nowadays most products and technologies support Web Services. Keep their pros and cons in mind when deciding what technology to use. Java for example provides better support and a better runtime for Web Service development and XML-processing than relational databases.

Large XML documents. Avoid creating Web Services that receive, process, and/or send very large XML documents. XML processing is resource-intensive and relatively slow and therefore not well equipped for handling bulk data. Use other technologies such as database technologies or ETL tools for that purpose.

Quality of Service (QoS). It’s easy to develop basic Web Services-but it’s hard to make them robust, secure, and scalable (enough). Address these QoS (or non-functional) issues in the beginning of the project instead of discovering that requirements are not met at the end of your project.

Annotations. Be careful when using vendor-specific annotations (as opposed to the general annotations defined in the JAX-RPC, JAX-WS, and JAXB standards). Although vendor-specific annotations such as those in WebLogic can be very powerful they break portability of Web Services and tie them to a specific runtime.

Migration to WebLogic. See this blog for migrating JAX-WS Web Services from JDeveloper 10g/OC4J to JDeveloper 11g/Weblogic. Note from the blog that a bottom-up approach was used. After migration the WSDL was changed (among others the namespaces were changed) causing the invocation to fail. This is a typical example illustrating the pros of using a top-down or meet in the middle approach.

Next post in this series will be about best-practices for Oracle ESB and Mediator (FMW 11g).