In my last article I tried to show how to find the different web services that an organization could expose to their customers, how to separate them and finally how to expose the operations (methods) inside one service. In this article will concentrate on only one operation, RenewDrivingLicense, and see how this should be defined with help of schemas (XSD).
The operation RenewDrivingLicense has two messages associated with it. It is one that contain the request to the operation and one that contain the response from the operation. (We could also have a third which is a special message that the operation will send if anything goes wrong.)
In my first article I showed an example of this service. In that example the request and the response was two documents, an application form and (hopefully) a driving license. This way to communicate with the service is called document literal and is the preferred approach when working with services. (A different method is to use rpc literal, which is more like method calls within a program where several parameters is used in the call.)
The first thing that I do with these documents is to name them. I use that by combining the name of the operation and, as the second part of the name, "request" or "response". This is not only a practical way to name things. This is done because we want to make the documents strict related to the operation. What do I mean by that?
We are still working on the contract of a service and its operations and messages. When we do that, we have to be as explicit as possible so that other could use it. (This is a long discussion that we could dig into deeper some other time.)
How to describe the documents?
The documents should of course be described as Xsd schemas. But it is not always easy to start writing them from scratch. We probably have to model them in some way. Currently I use two approaches to do this. We could use Uml to describe them as class diagrams or we could start writing examples of the documents in Xml. I prefer the first way when I do larger system. I think also that this is the preferred way when we start to have many schemas in a library. (This approach will I describe in the next article of this series.) The second way is still good to have when you start. It's also simple to have as a base for discussion.
Below is an example of these documents, the request and the response, as xml.
The xml has two other advantages:
1) Xsd Schemas can be generated from them.
2) They could later be used in tests as test data.
From Uml/Xml to Xsd Schema
The easiest way, as I said before, is to generate schemas from the xml examples. This could be done in Visual Studio. A different way is to use Xml Spy and start writing the schema.
This is really simple to do. The problem arise when we starts to do this on a larger scale. We will soon have the possibility to reuse parts and this is not easily done if we use this simple way to make schemas.
This will I talk about in my next article. To be continued...
Comments