Vendors

[Vendor representative],

I knew at the start of this process you were unlikely to change your implementation soon, certainly not within timescales which we could take advantage of for our delivery. However, I strongly disagree with your comments around SOAP Faults.

Your current implementation makes it difficult for consumers to work with your API and creates significant additional work to deal with error conditions returned from the API. When your service returns a response and I have to interrogate that response to find out if the request was successful, this is extra work for me. Were your service to return SOAP Faults, I can do something like the following (this is code from an internally developed web service at [my employer]):

try
{
      FindResponse findResponse = userService.Find(findRequest);
      Session["LoggedInUser"] = findResponse.User;
}
catch (FaultException<UserNotFoundFault>)
{
      // rather than quit just return the user being unknown
      User user = new User();
      user.Fullname = "Unknown User";
      this.Session["LoggedInUser"] = user;
}

You can see that I am able to deal with the SOAP Fault returned from the User Service using normal exception handling. In this particular use case, the application does not care that the user is not found and can continue. Other consumers of the User Service may choose to act differently, maybe the user not being found is a problem for other consumers and they can act accordingly.

Where I have to examine the response from a service to see if it was successful or not (as in the case of the [vendor] services) I have to start examining response objects rather than using exception handling. This is unnatural and prone to bugs. This creates unnecessary work for me as a consumer of your service (extra development, extra testing).

Using SOAP Faults, I can also deal with different error conditions easily:

     try
     {
           // Call some service
     }
     catch (FaultExcpetion<BusinessErrorA>)
     {
           // Do some corrective action
     }
     catch (FaultExcpetion<BusinessErrorB>)
     {
           // Do some other corrective action
     }
     catch (FaultExcpetion<BusinessErrorC>)
     {
           // Do something else
     }

I have no such options with your service and I have to jump through hoops to look at the response object to find out what happened.

The problem is compounded further when using BPM/integration/messaging platforms like BizTalk. In BizTalk there are standard Orchestration steps/tasks to deal with exceptions. However, the lack of SOAP Faults in your service means there are no exceptions so I have to devise a custom solution to see if there was an error in the response object. Again, this creates yet more work for me the consumer of your service.

Furthermore, the error messages you provide are simply serialised exceptions, many of them are not helpful. We have seen your service return a “Null Reference Exception” which simply says “Object reference not set to an instance of an object”. As the consumer of your service, what am I supposed to do with that information? What remedial action can I take? I don’t know because I have no way to know what went wrong. Looking at the User Service example above I know what errors to expect (the SOAP Faults in the service contract) so I know what the business logic should be for the consumer. Even when your service might return a helpful error message, I have no way of knowing I will get it without the trial and error of calling your service to find out. Again, this is more work for me.

I’ll re-iterate my previous comments that as per the SOAP specification, errors should be returned as SOAP Faults (http://www.w3.org/TR/soap12-part1/#soapfault).

It may be more effort for you to provide SOAP Faults in your service contract but as the publisher of a service it is your responsibility to do so. As a consumer your service, who is paying for the product, I expect you to do so. Yes, SOAP Faults mean you have a standard set of error messages. If you are unable to provide these because you do not know all of your error conditions, as a publisher of a service, you have bigger problems. This also links back to creating a lot of work for the consumer of your services. If you do not publish the list of error conditions, that does not mean error conditions do not exist, it means your consumers have to find them by trial and error.

You have shifted the cost of maintaining a set of SOAP Faults from yourself to the consumer who must come up with a custom way to find out if there is an error, work out the fault conditions by trial and error and guess at what remedial actions might be. This creates a lot of extra development and testing for consumers. As a consumer of your service, who is paying for it, I am less than happy with this.

I strongly suggest you reconsider your position for future releases of your product.

Regards,

Callum