Best practices for creating web services using webMethods IS

Hi all,

Can anyone recommend a set of best practices for architecting, building and running web services under webMethods? Are there any processes (such as retries and queuing data in the event of failure) that should be created?

Thanks,
Tom

I don’t know of a document from webMethods that sets forth any best practices for using creating web services using webMethods IS 6.x.

The list below assumes you need to create or expose dozens of web services and that you are not using an XML security appliance or a web services intermediary or web services management tool such as ServiceNet 6.5.

  1. Study and become familiar with the general web services interoperability best practices captured in the WS-I Basic Profile 1.0 and WS-I Basic Security Profile 1.0. You will not be able to easily adhere to all of these best practices using the current release of IS, but they will inform your decision making and identify interoperability issues that need to be managed.
  2. Adopt a top-down, WSDL-first or, at least, message first approach to designing your web services rather than looking at a folder full of IS services and trying to figure out how to expose them consistently. An excellent book on this topic is Thomas Erl’s Service-Oriented Architecture: Concepts, Technology and Design.
  3. Create web services using only SOAP document / literal style of messages for maximum interoperability
  4. Design and build a custom SOAP processor that handles all processing of SOAP messages and allows your services to be invoked with only IS documents for input.
  5. Provide some type of service metadata repository to be used by the custom SOAP processor for things like configuring some behaviors such as logging, auditing, schema validation, custom security requirements, etc. on an individual service basis. At the least this repository should hold the document types into which the payload of the soap request message should be place or against which the XML validation should be performed.
  6. Adopt a WS-Security approach that fits the needs of your application and business requirements NOT one that happens to be supported by some vendor’s toolset. This may require building utilities to handle tasks such as XML signature and XML encryption as these basic services are not yet provided by Integration Server.
  7. Give proper consideration to how your web services security approach should be integrated with your organization’s identify management solution. Leverage existing identity management tools where they exist and attempt to avoid island-of-automation solutions such as only using the IS identity information.
  8. Don’t write the first line of web services code before you have invested in some decent XML Schema and web services testing tools. XML Spy is a defacto standard, but others will work nicely as well. Both SOAP Sonar Personal Edition and PocketSoap TCPTrace are free and highly useful. Other possibilities are Parasoft SOATest, Mercury ServiceTest and Solstice Software. The new Eclipse WTP plugins also show promise.
  9. Understand what development tools the consumers of your services will most likely use and plan to generate test harnesses that use those tools.
  10. Build and deploy simple “ping” tests early in the development cycle. While these services should perform something extremely simple such as returning a timestamp, they should use the same security approach and protocol (e.g. HTTPS) as the production services will use.
  11. Invest in a comprehensive web services testing suite and build regression tests in parallel (or before) developing the services themselves. One good place to start is Solstice Software.

Feel free to chime in with other additions.

Mark

Mark,

I have several web services that are RPC. When I began the development of these services I checked the webMethods training manual and it stated that you should use RPC unless you have a specific reason not to. The services that I have are all internal and are very simple, they take in a few parameters and return information based on those parameters. I currently have several Java clients that are using the services and have had great success.
I keep reading that doc / literal is the way to go, so my question is, for what I am trying to accomplish what is wrong with using RPC? Should I be switching these services to be doc / literal.

Thanks
-Adam

Nothing is wrong with rpc/encoded as long as you don’t care about interoperability with external consumers who may be using soap stacks that can’t use the services you are exposing.

If you are exposing only internal services that will only be consumed by other webMethods IS clients, then you should be just fine. Of course, if that is your goal, web services may not be the best route anyway.

The training material you are referring to is obviously based on what is offered in the product, not on best practices.

There was a time when WM wanted to provide the “premier web services development environment”. That vision seems to have been abandoned a couple of marketing slogans ago.

Mark

Most excellent list!

Adam,

As Mark indicates, the general tendency for interoperability is using doc/lit style. One issue with RPC/encoded services is a tendency to expose the programming language semantics of the service implementation. Exposing behavorial–instead of concrete data–descriptions in an operation signature can leave much to be guessed by the service consumer. Doc/Lit succinctly captures the intended use of XML and Web Services–explicit data exchange between application components. How you perform your data binding is up to you.

Another (potential) differentiator is the ability to perform schema validation on the message exchanges. Schema validation cannot be performed on RPC style services since some portion of the payload is conveyed from the WSDL binding. Doc/Lit services contain everything in the WSDL enabling full schema validation. This proves valuable in scenarios where intermediaries are used to enforce enterprise wide policies.

My $0.02.

Cheers,

Ed

If you decide to implement doc/literal and therefore a custom SOAP processor the following thread may be useful to you:

http://www.wmusers.com/forum/showthread.php?t=6468

I faced this some year ago. RPC style services work fine with java clients but does not work with .NET stack client side proxy generator.
They had to manually reconstruct the entire soap and send over http. This explains why doc-lit style is recommended.

Define Contract First. Top down approach is the best way to go. This gives more control over contract definition and consequently creation of Good WSDL that can be utilized properly in java as well as .net platforms. In bottom up approach Some time unnecessary document get created. I have used Doc–lit and it worked fine with me.