David Pallmann’s WCF Tips  #1 - Service Interface Design

Service Interface Design

Design Service Contracts that are Themed and Indivisible

Tip: Ensure service contracts have a theme (purpose). Avoid combining unrelated service operations in the same contract; only include operations that contribute to the theme. This is also a SOA best practice.

Rationale: A service interface is supposed to be indivisible—that’s why we use the word contract. If a service contract has a purpose or theme and all of the operations in the contract contribute to that theme, the contract design is likely to be strong and survive. In contrast, throwing many unrelated operations into the same service contract under a weak premise, such as “all the public services my company exposes to partners”, is not likely to stand the test of time.

What if I Don’t? The longevity of your service contracts may be compromised.

Examples:

·         A bad example is a service whose theme is “Data Access”: this is far too vague a purpose for a service and invites every operation method that reads or writes to find a home here.

·         Another bad example is a service whose theme is inventory control but contains operations for both inventory control and truck delivery routing. Although the theme is reasonable, the operations do not all contribute to the theme, threatening to fracture the service into multiple services down the road.

·         A good example is a service whose theme is order placement, and whose operations pertain only to creating, updating, canceling, or inquiring the status of orders.

Design coarsely-grained methods

Tip: Your service should favor coarse methods that are called less frequently as opposed to granular methods called frequently. In other words, think chunky. This is also a SOA best practice.

Rationale: Invoking a WCF service operation has unknown expense. Factors affecting expense include transport, distance, security model, encoding, reliability level, and transactability. Therefore, the best practice is to always assume service invocations are costly and seek to minimize them.

What if I Don’t? Overhead will increase, possibly substantially.

Example: Your service needs to provide an operation for retrieving the transaction history of a client. A bad approach is to require a separate call to retrieve each individual transaction record. A good approach is to provide the full history as the result of a single call. An even better approach is to allow the scope of the results to be specified by the caller (such as a date range).

Take Advantage of One Way Operations

Tip: Use the most efficient messaging pattern for each operation. Don’t return a result if there is no use for it. Specify the asynchronous IsOneWay=true setting for an operation if a client doesn’t need to wait for the operation to complete.

Rationale: By default, a service operation is accessed in a request-reply pattern, and a client blocks after making a request until a reply has been received. This is true even if the return type of the method is void. However, service operations that don’t return a value can also be marked one way which allows a client to continue without waiting for a reply.

Example: Your service contract includes an operation named Archive which takes some time to execute. There are no results to return the client. You mark the operation IsOneWay=true so the client can initiate the operation without having to wait for its completion.

Use Data Structures Familiar to your Consumers

Tip: Use data types in service operations that are familiar to your clients.

Rationale: Often the designer of a service will have some notion of who the consumers will be. While this may be a diluted concept in the case of a public service open to the Internet, that is the exception rather than the rule. The majority of services are designed for consumption within a department, within a company, or within a company’s value chain or industry. Leveraging this knowledge results in a service contract design that is more natural to its consumers.

What if I Don’t? You’ll create unnecessary work for your consumers.

Example: A developer designs a service that will allow uploading of application forms. Because the intended consumers are in the health service industry, the developer supports an XML structure that is commonly used in the health care industry rather than inventing a new structure.

Maintain a Service Catalog

Tip: Create a catalog of available services and keep it up to date. This should include some machine-readable elements such as WSDL/XSD metadata, but also some human-readable documentation. Data structures should be defined and explained.

Rationale: If SOA is being seriously pursued in an organization, awareness of the services exposed by various projects is critical. A central catalog provides a single go-to place to learn about available services.

What If I Don’t? The left hand won’t know what the right hand is doing.