How can I describe a web service in plain english?

Question

Hi, I'm looking to document a few simple web services to a (mostly) non-technical audience. The rub there is "mostly". Some are very technical, and I want the form of the documentation to be correct and not to alienate them.

I can't claim to be hugely technical myself, but what I want to get across is the content of the data that is exchanged. I'm OK with the concepts of "exposing" the service, but what I want to document is the data that the requesting system will send in (ie. what the service is expecting) and the data that will be returned. For example, if the service was providing a delivery name and address for a transaction, the requesting system might send an transaction number and customer id.You might document it like this:

Request - Transaction Number() - Customer Id()

Response - Transaction Number() - Customer Id() - Delivery Name() - Delivery Address()

Now that is obviously "Mickey Mouse", but what I was wondering is if there is a "standard" convention & syntax for such documentation. I don't want to go down the whole WSDL route, just a clear English description. Anyway, great site , this is my first posting, so thanks for any responses. Regards Peter

Answer 1

There are several standards for that kind of documentation.
You could take a look at BPEL.

Answer 2

WSDL would be the formal defintion, and if you have the skills then I would capture the data in WSDL. If you use the right tools that can then be presented in a nice diagrammatic way.

I would examine the eclipse tooling, see if you can pull out a few pictures from that.

It would be possible to model the interface in UML, but it's not clear that this will be more consumable than other diagrams.

Answer 3

If you have access to SSIS (Sql Server Integration Services) you could create a very simple package mapping between the source and the webservice.

This will show in a graphical fashion as you can show the mapping between the two.

You can also use UML to help, and here is a link where the author is trying to extend UML to help diagram webservices.

http://webservices.xml.com/lpt/a/1259

Depending on what tools you use, I have used Eclipse to create a BPMN diagram to help explain a system using webservices to a largely non-technical audience.

http://en.wikipedia.org/wiki/Business_Process_Modeling_Notation

Answer 4

I think the UML sequence diagram is the most appropriate to describe protocols like Web services communication ...

If you want something more close to the composition implementation you should look at the BPMN representation

Sequence Diagrams example :

BPMN example :