This post wasn’t part of the original series, but I have decided to add it because of a project I am working on these days.
Most of the times I have been involved in the server side of web services, developing web services, but in this opportunity I am consumer of web services.
When reviewing the technical specs of the web services I have to consume I found that each web service returned a complex type that contains the following fields:
- Result: an integer that represents the result of the invocation, (1) successful invocation, (2) Invalid parameters, (3) Internal service error, and so on.
- Errors: in case the result be (2) it details the name of the parameters that are not valid.
- Data: the business information expected as the result of the invocation.
This approach is not bad, but I feel it like been reinventing the wheel. Maybe it is because of my object-oriented programming background. I am used to use exceptions to handle errors. Most of the technologies that give support to soap protocol provides a way to work with exceptions to manage errors.
When you call a web service and an error raises during the process, a soap fault message should be used to communicate the error. This fault message contains:
- Code: that allows the fault to be classified in one of the following categories: VersionMismatch, MustUnderstand, DataEncodingUnknown, Sender and Receiver.
- Reason: provides a human-readable explanation of the fault
- Node: provides information about which SOAP node on the SOAP message path caused the fault to happen
- Role: identifies the role the node was operating in at the point the fault occurred.
- Detail: is intended for carrying application specific error information
No matter what technology you used to work with SOAP, most of them provide a class to represent a Soap Fault, that is typically called Soap Exception. In the case of .NET there is a SoapException. This way if you are using .NET to consume a web service using Soap, .NET will generate a proxy object for you to call the web service, when you call this service you should do it inside a try-catch block adding 2 catch statements one catch for a SoapException and another catch statement for a System.Net.WebException, in case that no connectivity can’t be established.
If you are not familiar with the .Net Platform, DataSets are objects analogous to a database in memory. A DataSet contains not only a collection of DataTables, but also information about the primary keys and relations between the tables it contains. I ‘ve seen some people using DataSets to move data between the different layers of the application. I don’t like it, but that is part of other post, the big issue is when somebody starts using DataSets to build Web Services to interoperate with other technologies/organizations. This is a sad design decision because the way DataSets are serialized is not always understandable for non .Net consumers. The reason for this is explained very clearly in detail in this post by Paul Ballard.
Well, lets’ start by making the distinction between what was the original idea and what is the people doing now.
Originally Web Services were thought to share information between applications. The applications can be develop in different technologies and can also belong to different companies. For two applications to be able to share information they must agreed two things: the format the information will be structured and the way (transport) the information will be sent/arrived.
This problem is not new. As you can imagine before the raised of Web Services there were some attempts to solve this problem (like EDI and CORBA) but none of them were successful (unless in terms of industry adoption).
Web Services result to be a good solution and the development tools started to provide very useful features to work with them. Then developers started to use Web Services for some other scenarios like communication between the presentation layer and the business layer. But in most cases these two layers belong to the same application and are developed with the same technology, so it could be better to use some other protocols (like REST, netTcp or RMI) to obtain a better performance.
To some people this could be a very simple question today, but I think that there are still some confused people around. I remember one of the last projects I was involved, we were build an application that should exchange information with an external application, the technical person that spoke to us when we tried to connect both applications called web service to a simple ASP page that returned data in a raw string. Well this situations leads me to this post.
When we talk about web service we are referring to a technology stack that include HTTP and SOAP among others. A web service is a software component that can be accessed by sending SOAP messages following the rules defined in the corresponding WSDL document. For those that are not familiar with this terms here is a short glossary with some common terminology in the world of Web services:
- SOAP: Simple Object Access Protocol, it specifies how to create the messages, its parts, how each part should be used.
- WSDL: Web Service Definition Language, it is just a XML document that describes how to interact with an specific web service. Every Web Service must have an associated WSDL. The only thing needed to consume a web service is its WSDL.
- HTTP: Hyper Text Transfer Protocol, it is the main transport protocol of Internet.
- UDDI: Universal Description, Discovery and Integration, defines how to maintain a structure of directories to share information about web services.
I have been working with web services for a long time, I have came across with many design and implementation issues and I have reviewed many web service applications. During the last years I have been asked the same kind questions several times, and that is why I have decided to write this series to write down all the answers to that questions. The posts I have in mind at this moment are:
- What do we mean when we say “Web Services”?
- What do we use Web Services for?
- Please don´t use DataSets in your Web Services
- Tools for Web Services developers
Well, this all for now and walcomen to this series, I hope you to enjoy it.