Documenting a SOAP API: The Reporting Services Web service
I'm often asked, especially by those developing Reporting Services' Web service clients using straight SOAP messages, why the decision was made to document the Reporting Services Web service methods from the syntactical perspective of the .NET languages VB and C#. There are several reasons for this. Early on, we had planned to include XML representations of each Web service operation as it would appear in a SOAP message, but the cost of maintaining such documentation was high, especially as the product was in the early stages of development. We found that most of our customers, integrating reports into applications using the Web service, were .NET shops using primarily Microsoft development technology. It made sense to offer documentation and samples that supported their development efforts. Another reason was precedence. At the time, Reporting Services was just one of two Microsoft products with a complete, published Web service interface; the other being Mappoint .NET. We studied the Mappoint method of Web service documentation and wanted to be consistent, while at the same time, making sure that our customers would have the information they needed to be successful. Mappoint laid a strong foundation for Web service documentation and we wanted to follow suit. As stated previously, we expect that the majority of developers of Web service clients in Reporting Services will be working with Visual Studio and the .NET Framework. That is our primary development scenario for this release even though that Reporting Services WSDL is W3C compliant and adheres to the standards of that organization. In the future, we may look to include a "SOAP syntax" section along with each method topic, but that is not high on the documentation priority list. We do have some customers using non-.NET languages such as Delphi and Cold Fusion who at times struggle to get the right SOAP syntax. For those who need some help, here are a few tips:
1. If an argument to a Web service method is optional, leave the element out of the message entirely. Many of the samples that ship with the product pass null values for optional input parameters. This is required when you use a .NET proxy. This has the same affect as leaving the element out of the SOAP message completely.
2. If your development kit comes with a SOAP trace provider, use it. You can write .NET samples such as the ones found in Books Online and then run a trace on your report server to view the SOAP representation of calling certain methods. This is acceptable only in a development environment of course.
3. In languages, such as Delphi, that do not support passing null values for string parameters, you may be required to work with SOAP messages directly. You may not be able to access some Web service operations with a proxy object.
Okay, as usual, if you have comments on Web service documentation, what you like and don't like, feel free to let me know.