WSDL best practices

Question

Hi, I'm developing a SOAP application that integrates with a 3rd party. I think the WSDL of this third party is very strange. I'm pretty new to SOAP, so I don't want to go asking them to fix it if it isn't broken. Here's some things I've noticed that I consider wrong about it, though I'm sure it's technically a valid document (hence the reason I wrote "best practices" in the title). Also, I'm using gSOAP as my SOAP library, which may be why I think some of these things are weird (I'm even newer to gSOAP than I am to SOAP in general).

1. they have interfaces specified for both SOAP 1.1 and SOAP 1.2 in the same WSDL. This causes gSOAP to generate twice as many classes as it needs to, since I'm only going to use 1.2.

2. all of their namespaces are http://tempuri.org. That shouldn't be like that, right?

3. despite defining a bunch of RPC calls, their WSDL uses the document format. I'm thinking of asking them to switch to RPC format because it seems that gSOAP won't generate methods that take C++ typed parameters for document format. Instead, it creates a new class for every API function's input and response data. I'll have to write another layer of wrapping around the gSOAP stuff to provide a reasonable API to the rest of my app if I can't fix that. Also, AFAICT, the XML that will be going back and forth would be exactly the same as it is now if they switched to RPC, so I don't think it would be difficult.

4. elements have minOccurs = 0 yet when I submit requests without them, I get errors returned back indicating they're required (sometimes even stack traces of null pointer exceptions). They should specify them as minOccurs = 1 if they're required, right?

5. nearly all of the web service functions specify a response that includes an integer to indicate success (really a boolean) and an error message string. Should they be using SOAP faults for this? I think it would be easier for my application to handle if it was a fault since gSOAP will let me figure that out really easily (and print the error message trivially).

Of course, I don't have high hopes that this 3rd party company will change their WSDL just because I've asked them to. At least I'll learn something... for all I know, none of these are wrong or even questionable. Thanks for your help.

Answer 1

1 - They probably consider this a feature. :-)

2 - That's horrible.

3 - Lots of people recommend this. It's called wrapped format.

4 - You're correct.

5 - It depends. Theoretically, you're probably correct, but in practice lots of SOAP toolkits don't have very good support for SOAP faults, so they might have deliberately chosen to not use exceptions.

Answer 2

What you have encountered is the typical third party laziness when creating their web services. I'd imagine you won't have much luck trying to reason with them, however you can hand edit the WSDL to remove the 1.1 definitions.

Answer 3

Sounds to me like the third party you are trying to interface with doesn't know web services either.

From your description, it sounds very typical of a Microsoft ASP.NET web service implementation, the third party writes a little VB or C# to interface what they have to offer, pushes it to an ASP.NET server and calls it a day, depending on the ASP.NET engine to auto generate the WSDL upon request.

You could ask them to not supply SOAP 1.1 definitions, but I don't think they will help you , because they don't know how. You could ask them why the namespace is tempuri.org and I'm sure their response would be something like "We'll have to look into that" when what they really want to say it "It is??" because they don't know why either.

The namespace is controlled by a compiler directive in the code and tempuri.org is the Microsoft default (don't recall what it's called atm sorry). Of course the value of the namespace doesn't really matter a whole lot (aside from just looking weird) as it is really just intended to provide a unique string identifier for variable name resolution. Maybe the other things can be controlled in a similar manner, I don't know, I don't really know web services or ASP.NET or any of that stuff, not a big fan of the technology myself.

Answer 4

Firstly nobody actually writes WSDL -- its generated by tools. You vendors tools probably insert the CORRECT urls for the namespace and probably has some radio buttons saying -- V1.0, V1.1, Both. The vendor probably had some existing non-SOAP code and used some tools to wrap them as a SOAP service.

Nobody writes WSDL so you shouldnt read it! Get a decent tool set, something like SOAPUI will decode the WSDL and allow you to browse it without your head exploding. Its Java but its the best test tool whatever language you code in.

My SOA experience is mostly in Java where you are spoilt for choice as far as libraries and tools are concerned. C++ is probably less mature in this area but it really sounds like the problem is the tool choice rather than the WSDL. In the real world you will be presented with less than perfect WSDL so your tool should be able to deal with it in a reasonable manner.

Answer 5

I would like to be a little more general about best practices for WSDL creation:

1. Contract First Devlopment
In contrast to James I would strongly emphasise on the usage of the Contract-First method, because it empowers the developer to use the full capabilities of XML (restrictions, patterns, ...) and from there it is fairly easy to generate code for any programming language. One other reason is that the schema in the is the contract between the two systems talking to each other. If the developer creates the WSDL from code, technical dependencies on the specific programming language might be introduced (datatypes, ...).

2. Document/literal style
Validation of RPC-encoded SOAP can be tricky, XPATH queries and XSLT transformations are merely impossible as well and this style is depricated anyway.

RPC/literal also causes problems with validating the XML (account for certain naming conventions). Some SOAP engines drop schema defined namespaces consequently validation becomes impossible.

Using Document/literal style the SOAP body is completely processed as an XML document, which can be validated, transformed and queried in a standard way.

3. Separation of concerns
Separate the schema definition from the WSDL file itself by using and directives. This fosters the reuse of schemas and the separation of namespaces into different .xsd files and also reduces the size of the file ;)