Service Interface

Retired Content

The Web Service Software Factory is now maintained by the community and can be found on the Service Factory site.

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies.
This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Retired: November 2011

You are designing an enterprise application, and you need to make some of its functionality available across a network. This functionality needs to be accessible to various types of systems, so interoperability is a key aspect of the design. In addition to interoperability, you may also need to support different types of communications protocols and accommodate varying operational requirements.

How do you make pieces of your application's functionality available to other applications, while ensuring that the interface mechanics are decoupled from the application logic?

While designing your application, you must address the following forces:

  • It is desirable to separate elements that are responsible for the application's business logic from the elements responsible for communication protocols, data transformation, and fulfillment of service contracts. Doing this furthers the general design objective of separation of concerns.
  • Consumers of your application may want to communicate with the application using different technologies.
  • The application itself may impose different operational requirements on different consumers. For example, your application may have security requirements that authorize consumers internal to your company to perform update operations and delete operations, and consumers that are external to your company are only authorized to perform read-only operations. Or, for example, different consumers may need different transactional support from the application. To some clients, the context in which specific transactions occur is not important, and other clients may need precise control of the transactional context. A handle to this context might then be passed to other elements of the application as needed.
  • The application's ability to respond to changes in the business environment in a timely manner is greatly enhanced if changes to the business logic are isolated from the mechanisms used by consumers to interact with the application. For example, the fact that a particular set of business logic was implemented in a custom built component and then later implemented as a wrapper around a packaged solution should ideally have no impact on the consumers of the application.

Use the Service Interface pattern to describe the behavior of a service and the messages required to interact with that service. The service interface does the following:

  • It describes the operations that your service provides that a client can use.
  • It describes the format for information being passed to and from operations.
  • It describes the message exchange patterns that the service implements, such as request/reply, one-way, and duplex.

Design your application as a collection of software services, each with a service interface through which consumers of the application may interact with the service.

A software service is a discrete unit of application logic that exposes a message-based interface that is suitable for being accessed by other applications. Each software service has an associated interface that it presents to the consumers. This interface defines and implements a contract between the consumers of the service and the provider of the service. This contract and its associated implementation are referred to as a service interface.

Figure 1 illustrates a service gateway consuming a service provided by a service interface. The collaboration between these two elements is governed by a contract.


Figure 1
Service elements

As Figure 1 shows, the service interface provides an entry point that consumers use to access the functionality exposed by the application. The service interface is usually network addressable, meaning that it is capable of being accessed by the consumer over some sort of communication network. The network address can be a well-known location or it can be obtained from a service directory, such as Universal Discovery Description Integration (UDDI).

A key aspect of the design of a service interface is to decouple the implementation needed to communicate with other systems from the application's business logic. The service interface provides a coarse-grained interface and preserves the semantics and finer granularity of the application logic. It also provides a barrier that enables the application logic to change without affecting the consumers of the interface.

The service interface implements the contract between the consumer and provider. This contract allows them to exchange information even if they are on different systems. The service interface is responsible for all of the implementation details needed to perform this communication. Such details include, but are not limited to, the following:

  • Network protocol. The service interface should encapsulate all aspects of the network protocol used for communication between the consumer and service. For example, suppose that a service is exposed to consumers through HTTP over a TCP/IP network. You can implement the service interface as an ASP.NET component published to a well-known URL. The ASP.NET component receives the HTTP request, extracts the information needed by the service to process the request, invokes the service implementation, packages the service response, and sends the response back to the consumer as an HTTP response. From the service perspective, the only component that understands HTTP is the service interface. The service implementation has its own contract with the service interface and should have no dependencies on the specifics of the technology that consumers use to communicate with the service interface.
  • Security. The service interface should be considered its own trust boundary. Consumers of the interface may need to be authenticated by the service and roles associated with consumers can be used to control access to different operations exposed by the service.
  • Service level agreements. The service interface has a significant role in ensuring that the service meets its service level commitments to a specific set of consumers. Service interfaces may implement caching to increase response time and reduce bandwidth consumption. Multiple instances of a service interface may be deployed across a load-balanced set of processing nodes to achieve scalability, availability, and fault-tolerance requirements.

With the Windows Communication Foundation (WCF), a service interface is defined through the use of service contracts, message contracts, and data contracts, as follows:

  • Service contracts define the methods of a service. A service contract specifies the data an endpoint communicates to the outside world. Basically, it is a collection of messages organized in operations that have basic Message Exchange Patterns (MEPs), such as request/reply.
  • Data contracts specify what data is sent in the WCF infrastructure.
  • Message contracts enable you to control the message headers generated when a message is created. The topics in this section provide the basics needed when creating WCF applications.

The following is an example of a data contract named GetCustomerByID that is defined in the ICustomerManager service contract.

namespace ServiceContract
    using System.ServiceModel;
    [System.ServiceModel.ServiceContractAttribute(Namespace = "http://Microsoft/WSBAT/ServiceContract", Session = false, Name = "ICustomerManager")]
    public interface ICustomerManager
        [System.ServiceModel.OperationContractAttribute(IsTerminating = false, IsInitiating = true, IsOneWay = false, AsyncPattern = false, Action = "GetCustomerById")]
        DataContract.Customer GetCustomerById(DataContract.CustomerId request);

This section describes some of the more significant benefits and liabilities of using this pattern.

The information in this section is not intended to be comprehensive. However, it does discuss many of the issues that are most commonly encountered for this pattern.


The benefits of using the Service Interface pattern include the following:

  • The service interface mechanics are decoupled from the application logic. With this separation, a consumer can easily add new interfaces and change the implementation of the underlying application with minimal impact on consumers.
  • Decoupling the service interface code from the service implementation code enables you to deploy the two code bases on separate tiers, potentially increasing the deployment flexibility of the solution.


The liabilities of using the Service Interface pattern include the following:

  • Many platforms make it easy to expose application functionality. However, this can lead to a poor decision in terms of granularity. If the interface is too fine-grained, you can end up making too many calls to the service to perform a specific action. You have to design your service interfaces to be appropriate for network or out-of-process communication.
  • Each additional service interface provided by a service increases the amount of work required to make a change to the functionality exposed by a service.
  • The Service Interface pattern adds complexity and performance overhead that may not be justified for very simple service-oriented applications.
The basis of this topic is from Service Interface on MSDN.