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.

Comments

• Anonymous
  February 25, 2004
  I am likely to want to access RS via Delphi. I was thinking of writing another webservice which talks to the RS web service but will offer a simplified and Delphi friendly interface. Does this sound sensible ?
  e.g. I was thinking of converting rs.Credentials = System.Net.CredentialCache.DefaultCredentials; to Delphi. This way I can still write this using C# code inside my webservice, I could just have a logonmethod with username and password for Delphi to call.
• Anonymous
  August 10, 2004
  Hi ,
  Is there any other way of developing Reports using Reporting Services apart from using Visual Studio .net.
  
• Anonymous
  August 10, 2004
  Not from Microsoft. You can check out the partner pages at www.microsoft.com/sql/reporting. Remember that you do not need the full VS.NET to do report design. The lightweight VB.NET (less than $100) will do the trick.