SOAP Web Services — best practices from the field

In enterprise integration, SOAP web services are the standard. REST is trendy, but when integrating banking systems SOAP with WS-* standards is still the safer choice. After two years of intensive deployments, we share our best practices.

WSDL-first approach¶

The WSDL is the contract. If you start from code, the contract is a by-product of the implementation. Rules: Document/literal wrapped binding, version in the namespace, shared types in a separate XSD, operations as verbs.

Implementation in Java EE¶

We generate Java classes from the WSDL using wsimport. The server implements the generated interface as a @Stateless EJB. GlassFish takes care of the SOAP stack and WSDL publication.

WS-Security¶

X.509 certificates for mutual authentication and message signing. Username/password token only over HTTPS. Configuration on GlassFish is complex but necessary for enterprise.

Error handling and versioning¶

Custom fault elements for business errors. Never expose a stack trace in production. Minor versions are backwards-compatible; major versions = new namespace and parallel operation.

Conclusion¶

SOAP isn’t sexy, but it is irreplaceable in enterprise. WSDL-first, WS-Security and a clear versioning strategy will save hours of debugging.