Web Service Best Practice made simple

Now while I like to stress that SOA isn't about the technologies and it doesn't have to use Web Services, lets face it the odds are that when you get to the technology its liable to involve them somewhere. There are some good, long, articles out there around all of the challenges and what you should do. But I've used a few simple rules to help me

1. Don’t expose functionality directly, always use a façade
1. Depending on the technology you can then log inside the face, error reporting etc. Some tools have these elements done for you.
   
2. WS-I compliance is a must if you have heterogeneous clients
3. If you are doing transformations, use a mediation approach (i.e. something between you can the caller and the consumer)
4. Publishing is a “phase 2” element for most organisations, don't worry about it
   
5. End points wise, if you are using “standard” J2EE then JAX-RPC (and now JAX-WS) are pretty well tooled up, if coding then AXIS 2 is worth a look.
6. If you are using something other than HTTP be aware that currently both end-points have to be using the same technology stacks
7. Remember that Point to Point WS is still Point to Point, if you are going to be doing quite a few of these then put in the patterns (e.g. mediation and a facade) that make lobbing in indirection simpler
   

Other good practice elements are to define the schema separate to the WSDL so your type definitions are independent (can cause versioning challenges though).

The biggest recommendation is to use a decent IDE with good WS support. In terms of documentation what I've done is design the WSDL and the data structure, then cut and paste the images from the tools of these things into the document. For each method on the WSDL I'd. define (in the doc) the pre-conditions, post-conditions and sometimes the invariant, brief overview of what the service is for and if there are any interaction patterns (call X before Y) then state them if simple (as pre-conditions) or if complex diagram the process. Then the WSDL is an appendix along with the Schemas.

Its not rocket science and from experience it doesn't need to be complex and if you are using REST I'd say that everything but 2 and 5 still apply.

The most important by a mile is the facade rule, it will save you a huge amount of pain over right-click exposing something internal.

Technorati Tags: SOA, WS, WSDL, Web Service