Every developer understands the importance of documentation; utility and maintainability of software depends on a chain of comprehension from the initial architect through the end user. Web services presume a level of automated facilitation of application composition and workflow process.
At least some documentation on the service has to be machine-readable, creating the foundation of Web Services Definition Language (WSDL). Architects and service designers can use WSDL as a critical documentation element and the key component binding development to workflow.
WSDL is based on a Web service model that says services are available at endpoints where you can exchange messages. The service is described by a set of interfaces representing operations (input/output) and faults (also input/output) that are connected to endpoints through protocol-defining bindings.
For those not experienced in Web service design and WSDL, it's probably helpful to draw a diagram to help visualize this process. Service users are on top, originating and receiving messages through endpoints identified by URLs and bound to service interfaces through the message protocols that tunnel from user to service.
Modern Web service development can start with the automatic creation of Web service shells from the WSDL that defines them, which insures services are correctly created and consumed. Obviously, that means you should start Web service design with WSDL creation and then fill the shell with your own code.
Approaches to Web service design and WSDL creation
Usually the first step in service design and WSDL creation is to conceptualize the kinds of message flows that will be supported, and the operations and faults that are included in the WSDL interface specification. WSDL allows for both client-initiated and server-initiated flows, but be wary of using the latter because they doesn't relate well to modern RESTful service practices of client-driven exchanges.
In a green field, beginning your Web service design with the output of the EA framework is smart.
If you expect your Web services to be familiar to Web designers, stay with one-way or request-response formats. If you do, you'll find WSDL 2.0 can be used to describe (with some limitations) RESTful services.
Architects disagree somewhat on how to start defining Web services using WSDL, particularly if the services aren't written yet. Some like to start at the service level, defining a service as a set of interfaces that describe its operations and as a set of endpoints through which it will be available. Others prefer to begin with the interfaces, describing the input/output operations and faults first, then assembling them into services that are then assigned to endpoints.
While either way works, it's likely easier to relate an interface-centric approach to enterprise architecture function/process definitions because interfaces can represent elements in a workflow. In a green field, beginning your Web service design with the output of the EA framework (or an equivalent form of coupling to business processes) is smart.
The interface approach is related to what some call document WSDL and starts with the creation of a simple message structure (instance document) that describes the services by outlining general inputs and outputs. Doing this first lets you define the data elements, which let you select the schemas you'll need to reference. The data elements in the messages defined for the interfaces would be typed to associate them with specific format information.
One question that's often asked at this point is, "How many interfaces should a Web service expose?" In theory, several could be offered, but many designers and architects believe services should include only a few (often only one) closely related interfaces.
If there's a body of code already in place and exposed as Web services, you can relate the number of interfaces to the actual functions performed by a software component. If code isn't in place, the question of the number of interfaces per service is likely answered by determining whether all the interfaces rely on common resources. If they do, they can be considered part of the same service; if not, separate them.
Keep style attributes in mind
Don't neglect some of the style attributes of the WSDL interface specification. One example of such an attribute is wsdlx:safe, which means the interface defines a service that's not going to commit the caller to a commercial transaction. Be careful to define the fault side of the interface and not just the operations side because fault handling is critical in any service that involves relieving inventory, placing an order and so forth.
More on Web service design and WSDL creation
Architecture plan and design best practices
What you need to know about WSDL
When to parse WSDL files
The WSDL binding element describes the protocol to be used to support the interface. Bindings will often be operation-specific, meaning they may define a protocol specific to each of the operations (and faults) established in the interface. This is one of the extensions made to WSDL to accommodate RESTful access; you can specify the HTTP GET, PUT, POST or DELETE method.
Points relating to RESTful use of WSDL are often critical as organizations are struggling to address the question of REST versus SOAP. WSDL can be a valuable tool for creating consistency in service accessing and publication. With the latest revisions to WSDL, it's possible to define RESTful access with WSDL and use WSDL tools (at least those compatible with WSDL 2.0 or higher) with REST services. It may be that this enhancement to WSDL will be a step in blending the rigor and automation of SOA/SOAP and the flexibility and simplicity of REST. If that's the case, WSDL could become the bridge between these two service architectures. For service architects, that would be a very favorable outcome indeed.
About the author:
Tom Nolle is president of CIMI Corp., a strategic consulting firm specializing in telecommunications and data communications since 1982.
This was first published in October 2013