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).
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.
all of their namespaces are
http://tempuri.org. That shouldn't be like that, right?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.
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?
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
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 <wsdl:types> 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 deprecated 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 <import..> and <include..> directives. This fosters the reuse of schemas and the separation of namespaces into different .xsd files and also reduces the size of the file ;)