WCF is a great addition to the .NET framework.  Like all parts of the framework it introduces a lot of new concepts to learn.  Sometimes it’s hard to separate those technical concepts from the decisions like, “What is the best way to architect this service” or “How should I name things?”

Simon Segal, a fellow .NET and SOA junkie posted back in November about how he names operations and messages within WCF and the nServiceBus framework (an open-source Enterprise Service Bus).  Simon, like I do, follows a convention of naming in relation to the business events the operations and messages represent.

When it comes to naming operations we not only imply some intent of the operation we also imply what data might be needed.  When designing services that are more coarsely grained you often run into issues with what data is really required for the service to perform its work.  Simon linked to an article from Thomas Erl, a respected authority on SOA, in which Thomas made the following statement (my emphasis):

Although it is practical and extensible, the use of optional parameters should be limited within Web services. Optional parameters can lead to convoluted service interface designs and a myriad of confusing data exchange scenarios. Additionally, the extent to which optional values can be accommodated is often limited by the underlying XML schemas that define the message structures. Standardized schemas that represent established corporate documents may impose rigid data structures.

Coming from the NIEM world I often emphasized that data exchanges only need 80% of what we think is needed.  There were times when people would want to exchange flags or indicators that could be derived from other fields or were not necessarily needed at all.  Any time we strayed away from the 80% the services became more difficult to consume and maintain.

Let’s Look at An Example

Factoring all of this in, let’s consider an example of how we might name service operations and messages.

Definitions:
Service Operation – A method you call on a service. 
Message – An input/output of a call to a service operation.
Message Parts – Data elements that are included in the message.

Problem: You need to name messages and service operations for a service that will allow customers to place orders for widgets.  This service should also allow orders to be cancelled.  Orders consist of a unique ID, a customer Id, and widgets. 

Request/Response example:

  • Service Operation PlaceWidgetOrder, Message: PlaceWidgetOrderRequest, Message Parts: WidgetOrder (Id, Customer Id, Widgets[] (or WidgetCollection))
  • Service Operation CancelWidgetOrder, Message: CancelWidgetOrderRequest, Message Parts: OrderId

Event-Driven example:

  • Service Operation: CustomerPlacedWidgetOrder, Message: CustomerPlacedWidgetOrderMessage, Message Parts: same as request/response example
  • Service Operation: CustomerCancelledWidgetOrder, Message: CustomerCancelledWidgetOrderMessage, Message Parts: same as request/response example

Notice the difference between the two styles.  In the event-driven style we talk about something that has happened (or is happening) and in the Request/Response style we talk in terms of what we want to do.  Each style has it’s merit and the style you choose will depend on the situation and the maturity of the partners involved in the service collaboration/data exchange.

Also notice that the event-driven example does not imply any type of response to the operation.  Typically event-driven systems will be asynchronously designed and the service operations will reflect that.

Why Messages?

Messages allow us to encapsulate the data needed for the domain as well as data we may need because of technical requirements.  Technical requirements may dictate that we have to log messages or protect messages in other ways (which could require message IDs, encryption keys, etc).  By encapsulating data in a message we also leave room to include the technical requirements within the same message and keep our domain model free of technical bits that aren’t really part of the domain.

How do you name your service operations and messages?

Simon and I would love to hear.  Leave a comment or tweet it!