Homepage of programmer Torben Warberg Rohde

Structuring extensive SOAP webservice APIs

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