Last year I spend some time building a webservice SOAP API for
the Metimus
system. Although it only covers selected bits of the full
system it is still fairly extensive.
In the process I spend quite some time figuring out how to
structure SOAP services when you go beyond the simple
"RegisterForCompetition" type services... so I thought I'd share,
since my attempts at Googling a solution where unsuccessful.
The problem I ran into
When you build a webservice API, the natural instinct is to
attempt to make it look like a true OO API as much as possible. So
you will want to:
- Use objects for parameters and return types instead of
primitives, which is no problem with the complex types of WSDL
- Partition your solution into multiple services, as you would
have multiple classes in an OO API (e.g. a CompanyHandler service,
a UserHandler service etc.)
Now the problem arises when you try to e.g. use a return value
"User" object from one service operation as a parameter for an
operation on another service. Your solution will not compile!
The reason is that even though you know it's the same
class, the client proxy-generator does not (whether it is .NETs
WSDL.exe, Java or any other environment). There is no way around it
- at least not without making life miserable for the client
programmer (and the reason we wanted it OO'ish and shiny was to
make it easy :-)
You have two basic choises: Either you
partition it into multiple services and use primitives for all
parameters - or you keep all operations in one big service and you
get to use objects for parameters and return values.
I ended up using the "one big service" option. To make it a bit
easier to maintain I then used the partial class feature of .NET, so I didn't end
up with one insanely large file.
Further info and examples
A full explanation of the problem including sample code illustrating the problem can be
seen here in this Experts-Exchange question I wrote. In
case you do not have an account, here are the resource-links that
was posted in the answer:
- Microsofts description
- Another explanation