W3C defines web service as: "A Web service is a software application identified by a URI, whose interfaces and binding are capable of being defined, described, and discovered by XML artifacts, and supports direct interactions with other software applications using XML-based messages via Internet-based protocols."

In software architecture literature It is agreed that the XML syntax to define the web service is WSDL.

Three Approaches

From a methodology point of view there are three possible approaches to design a web service:

• top-down: The architect first defines the Web service interface using WSDL and XML Schema (XSD) constructs, then generates implementation code for the service.
• bottom-up: from the developer environment like eclipse, we can create a web service and wsdl from an existing java code. The JAX-WS specification defines annotations to put in the code to define the service. 
• meet in the middle: combines the two approached above, but involves the development of code to manage the new interface as generated by the WSDL and the old API from the existing function.

The bottom-up approach as the advantage to quickly expose web service, and also permit to test within a java environment the implementation of the service. But this approach leads to have incompatible type definitions and so have multiple definitions for the same semantic.

There is a common acceptance among software architects to use a top-down or meet in the middle approach, and define the common interface within the portType declaration of WSDL. The XML Schema specification defines a broader range of constructs for describing message structures than Java. Some of these include choices, derivation by restriction, annotation. Therefore, it is better to define your interface using WSDL and XSD, and generate skeletal Java code.

Service Definition

A service interface should generally contain more than one operation. Operations defined as part of a single service interface should be semantically related. Business transactions related to the same data as for example a claim are mapped to operations within the same interface: ProcessClaim. Having one interface per business function may lead to have a huge amount of service interfaces. Service proliferation, in turn, results in service governance problems, making it harder to pursue effective code reuse.

if for example the data are coming from different physical systems, we could map the access to those different data sources with technical interfaces, and aggregate these interfaces into a single business interface.

The signature of each operation can support different set of approaches: synchronous/ asynchronous, stateless/stateful, header based or carrying payload, use of faults or not.

Asynchronous design means that once the client sent its message it does not know if the message was successfully delivered or not, and if the service was able to process it. This is a one-way operation. It may be a good implementation for a Event Driven Architecture, leveraging an ESB for message reliability and delivery.

Synchronous involves request-response operation. The client is blocked until it gets the response or a fault. Faults convey error information about failures that occur during the service invocation. Online application should leverage a synchronous definition of the service to ensure someone is taking care of the errors.

When designing a new service, do not mix synchronous and asynchronous invocation semantics in a single WSDL port type. If it is advantageous to support both semantics, define separate interfaces for synchronous and asynchronous invocations.

An important design consideration on the operation response message. It has to include some business semantic so that the client caller can do something in case of failure, like for example asynchronously ping the service for new response.

Exchanges between services can be stateful or stateless in nature. A stateful, or conversational, exchange between services occurs when the service provider retains knowledge of data that has been exchanged between the service consumer and the service provider during preceding operation invocations. Stateless interfaces are considered superior in the context of building an SOA. A stateless interface can be readily reused by many service consumer applications that are free to manage state in the manner best suited to each application.

The request messages contain data that will be used by the service to perform the business logic of the operation. These messages can also contain data (ins SOAP user-defined headers for example) that are more pertinent to system-level processing associated with the transaction. Such data can include service consumer identifier, service producer version number (play old - new service), time stamps,...