Service Versioning in SOA

Todd Biske

December 2008

Making a Change

For the next few months, the Center of Excellence paid off. Projects were identifying services early in the lifecycle. Those same projects were successfully identifying other potential consumers of these new services. Implementation technologies were being chosen correctly and interface design was being properly done. Most importantly, everyone felt the SOA effort was on track.

By this time, it had been almost two years since Spencer's team developed the Customer Information Service for the auto insurance and home insurance divisions. While these two groups were very happy with the results, no additional teams had leveraged it. Outside of the annuity project, this wasn't a case of projects going in another direction; it was more due to lack of opportunities. That was about to change.

Spencer was eating lunch in the cafeteria when Ramesh walked up. "Mind if I join you, Spencer?"

"Hey Ramesh, it's been quite some time. Go ahead and pull up a chair."

"Do you remember two years ago you tried to convince Ryan to use your Customer Information Service?"

"I sure do. I didn't want to show my face in the annuity area for about a month after that. He really wasn't very receptive to the idea."

"Well, I have some good news and some better news for you. The good news is that about six months later, Ryan decided to leave Advasco. The better news is that we've now got a major initiative to revamp a number of our systems in the annuity department. I'd like to take advantage of the Customer Information Service as part of that effort."

"That's good news Ramesh. I didn't harbor any resentment towards Ryan, but I'm certainly happy about having another potential consumer for the Customer Information Service. I'll put you in touch with the service manager for it."

"Thanks Spencer. That would be great. We're just getting started on our architecture, so the timing is perfect."

"Let me know if you run into any problems. I'm still part of the SOA Center of Excellence, so it's still my job to make sure it goes well!"

Spencer put Ramesh in contact with the service manager for the Customer Information Service, Maria. Maria had recently transferred over after her work on the account maintenance effort, and now had responsibilities for the Customer Information Service. In the meeting with Ramesh, she brought her technical lead, Craig, with her

"Spencer told me that you're interested in utilizing the Customer Information Service in some of the new systems you're building in the annuity department, Ramesh."

"That's right. We're rewriting a number of our systems, and based on what I remembered from Spencer two years ago, I thought we might be able to leverage the service."

"Great, I'd be happy to help you out. This is Craig, the technical lead who covers the Customer Information Service. He's here if you've got any technical questions. Have you had a chance to review the information available in the service repository?"

"I have. I reviewed the service interface, and while it certainly looks like there's enough there to warrant using the service rather than building our own, there's also a number of additional things that we'll need."

Craig responded, "What kind of changes are you looking for? Are there new operations that you need that are specific to the annuity area?"

Ramesh said, "There are two or three operations that we'd like to see, but most of the changes are actually in the message schemas for the existing operations. There are some additional attributes that we need, and some of the relationships between the attributes are different in our representation."

For the rest of the meeting, Ramesh and Craig went through the changes that Ramesh wanted to be made to accommodate his needs. In the end, it was clear that some changes to the existing schemas would have to be made. Maria asked, "We're going to need to go back and look over these changes, along with the integration approach for your existing database. What does the schedule for your efforts currently look like?"

Ramesh replied, "We're still in the initial stages of planning, which is why I wanted to make sure I talked to you now. Right now, the project sponsors would like to have something within six months, but they also know that nine months is far more likely. Since I have some flexibility in my schedule, why don't you take a week to look into the effort required for the changes, and let's work out the schedule then. Does that work for you?"

"That works for me. We'll get back to you next week with what we think it will take to implement the changes."

On the way back to their desks, Craig commented to Maria, "You know, while I don't have any concerns about getting the work done for Ramesh, I do have some concerns on how these changes are going to impact our existing consumers. Some of these changes are going to break the existing interfaces."

Maria said, "That is a concern. I know that there aren't any resources available to do any work on the home insurance side of things. Any suggestions on how we should handle this?"

Craig said, "Well, we definitely should make the existing consumers aware that a change is going to be made and at least get a clear idea of what the impact will be. If you can take care of that, I can take this to Spencer and the SOA Center of Excellence, and see what suggestions they have."

"That sounds like a good plan to me," replied Maria

Over the next week, the Customer Information Service team did the analysis required to estimate how long the changes would take to implement. Maria used the communication features of the service registry/repository to push out a message to the existing consumers about the pending change, and as she suspected, the biggest problem was going to be the home insurance system. Due to other priorities, the earliest they could even begin to make changes to their consumer would be nine months from now, potentially three months after the service needed to go live.

Craig met with Spencer and explained the problem to him. Spencer agreed to facilitate a decision-making session to explore the different options. Representatives from all of the existing consumers were there, along with Ramesh, Craig, and Maria

Spencer started the meeting, "I'm sure all of you saw the notification from Maria last week that some changes are necessary to the Customer Information Service in order to support its usage by the annuity department. The problem that we face is that these changes will break the existing consumers of the service, and not all of you can make the changes to your systems in the currently proposed timeframe. Let's start out by listing all possible options, regardless of whether we all presently agree or disagree on their viability."

Craig started out, "Well, if we're listing all possible options, the first one is toupdate the service, and then get whatever push we need from management to get resources allocated to the consuming systems so they can make the changes in the time required."

Maria replied, "Come on Craig, you know that we can't just pull resources off projects that easily."

Jason, from the auto insurance department, added, "Aren't all of these changes a result of the annuity department? Why can't they just include modifying our applications within their project scope? They already have resources allocated to their project."

Paul, from the home insurance department, replied, "Do you really want some developers that have never seen your application before mucking around in your code? I know I don't."

Spencer said, "Let's remember, we're listing all options, regardless of whether we all know that the option won't fly. We want to make sure we've explored all of the options. I'm going to just leave this as one option, since we still wind up with the same result, regardless of where the resources come from. I'll capture the concerns about the option."

Paul, from the home insurance group, added, "Okay, here's another option. Why don't we leave the existing service in place, and simply have the annuity project write a new service that just they use. Then, none of us using the existing service would be impacted."

Craig replied, "That's true, but isn't that going against everything we're trying to do with SOA? I thought we were trying to avoid redundant implementations of the same capability."

Spencer replied, "Duly noted, Craig. Just as with the last option, let's keep it on the board, and I'll make sure that your concerns are captured. Paul, that option actually triggered another one in my mind. In addition to having Maria's team write the new service for the annuity system, why couldn't they also keep the existing version of the service available in production for the rest of you? You can then migrate as your schedules allow."

Paul and Jason both replied in tandem, "That would work for us!"

Maria jumped into the conversation, "While I'm sure it would, that sets a very dangerous precedent for my team. How many versions of the service are we going to have to maintain? While it's a little bit better when all the implementations are owned by one team, we still have multiple implementations."

Jason then asked, "Isn't there a way to make the new service backwards compatible with the messages associated with the old service? That way, Maria's teamwould only have one implementation, but we could each continue to use our existing interface."

Spencer replied, "That's a very good question Jason. While we all agree that the service interface needs to change to support the annuity department's requirements, I don't know that any of us have thought about whether we can easily transform messages associated with the previous version to messages that will work with the new version, and vice versa. Craig, you're the one most familiar with the new proposed schemas. Do you think we could leverage XSLT to apply transformations for backward compatibility?"

"Yes, I think it's possible. The only concern I have is what impact this will have on the service implementation. Working with XSLT within Java code isn't the easiest thing to do, and as we make future modifications, that's just going to get uglier and uglier."

Spencer said, "There's another option for that. A year ago, we put some XML appliances in place for security purposes. I know they have XSLT capabilities and they're already in the request path."

Craig replied, "Of all the options, I think that one would work out the best. I really don't like the idea of maintaining multiple versions of the service, and having to maintain all of that XSLT code within the service is only slightly better. Allowing the annuity group to write their own goes against everything we're trying to do with SOA."

Spencer said, "Well, we know where Craig stands. Are there any other options that we should look into? No? Well, what does everyone think?"

Paul was first, "We know that we're not going to find resources to make the changes in all of the consumers at the same time, so that option is out. Likewise, it doesn't make sense for Ramesh's team to write their own service given our SOA goals, so that one is out, too. As for whether Maria's team maintains two versions of the service or utilizes some transformations somewhere, it really doesn't matter to me. From my perspective, both options give me the freedom to migrate at the time that works best for me."

Jason immediately added, "I agree with everything Paul just said."

Ramesh then offered his opinion, "Well, I certainly know that I don't want to give up any of my developers to work on Jason's and Paul's systems. We need every developer we can get right now. As for writing our own service, we've already been down that path two years ago, and now we're obviously changing the system again. If we had migrated to the service earlier, it would be one less thing that we had to touch as part of these changes. As long as Maria's team delivers my service on time for my projects, it doesn't matter to me what Maria's team chooses to do on their side."

Spencer replied, "Well Maria, it looks like everyone else thinks that we need a solution that will allow all of the consumers to continue to use their existing interfaces or the new one, but the details of how that happens is completely up to you and Craig."

Maria said, "Let's not jump to conclusions yet. If I'm going to maintain multiple versions, I need some kind of guarantee that the existing consumers will eventually migrate to the new version. If my team allows continuous use of the old interface for 12 months from the time the new interface goes live, would that be an adequate time to complete whatever modifications are necessary?"

Jason and Paul thought about it and decided that this was reasonable. For the past three years, they'd averaged an update every nine months.

Maria said, "I'll make sure to remind you, early and often, that the old version and its associated interfaces are going to be decommissioned. In the meantime, I'd like to first get the new version built. I'm going to need to keep both versions around initially just to compare messages. Ramesh's team can begin using the new service, and…" As she was talking, she stopped mid-sentence.

Spencer said, "Is there a problem, Maria?"

She replied, "Well, I was just thinking, how are we going to avoid having two URL's out there? The existing consumers are using a URL that points to the XML appliances, right? We want to apply transformations to that path. What URL will Ramesh's team use? We don't want to try to apply transformations to their requests."

Spencer said, "Fortunately, I don't think we'll need to do that. We'll need to talk to the team that operates the appliances to be sure, but I'm pretty sure that the appliances can apply processing based upon incoming attributes on the message. As long as we can determine which requests came from which consumer based on the message content, we should be able to control when transformations happen, while having all the existing consumers using a single URL. We'll obviously need multiple URLs behind the intermediary, but that will be hidden from the consumers."

Maria replied, "Okay, that eases some of my fears. Just make sure you find out quickly whether the appliances can handle it or not. Until we find out, can we set up a simple routing rule so that requests from the annuity group go to the new service, while the old ones stay where they are? That way, Ramesh can use the new service as soon as it is available, and Craig and his team can start working on the transformations for backward compatibility. I'd like to wait and see how that work goes before deciding whether to leave both versions out there for 12 months or to leverage the intermediary. We've never used that functionality before, and I don't want to take a chance on impacting Ramesh's schedule in case we run into difficulty. By keeping both services available in production at first, we can eliminate any dependency between the decommissioning of the old service and Ramesh's schedule."

Craig added, "From my point of view, that shouldn't be a problem. I can treat the new version as if it were a completely new service, as long as the intermediary shields the consumers from that change. I will need to check how we can manage both versions at the source code level, though."

Maria responded, "Good points, Craig. Taking all of this into account, I think this approach poses the least risk overall."

Spencer said, "Then we're all in agreement, right? Maria's team will build a new version of the service according to the new interface, and the old interface will be available for 12 months from the time the new service is deployed. Initially, both versions will be available in production, but Maria can decommission the old service before 12 months are up, so long as the new version can be made backwards compatible via XSLT transformations. Maria will notify all consumers prior to decommissioning the old service, since regression testing will be required to ensure that backward compatibility has been maintained. She will also notify all consumers as we get closer to the 12 month cutoff when the older interface will no longer be supported."

Everyone in the meeting agreed with this approach, and the teams went off and made it happen. Craig's team investigated the best way to apply the transformations, testing them using the latest Java libraries, as well as the XML appliances that Advasco had recently installed. They found that the XML appliances performed very well, and kept the programming model of the service very clean. While the Java libraries performed satisfactorily, the resulting programming model was not as clean as the team desired. With the use of the routing rules in the appliance, they were able to remove the older version of the service from production, while still supporting the older messages for the full 12 months as promised.

The Chief Information Officer's Concern

About two months later, Elena was in her monthly meeting with Andrea. Andrea brought up the subject of service versioning. "I understand there was quite a bit of debate around how to accommodate the needs of the annuity department in the Customer Information Service."

Elena replied, "I wouldn't say that there was that much debate. Spencer facilitated a decision-making session, and I encouraged all of my team to put all of the options on the table, regardless of their viability. The real debate came down to whether or not Maria's team wanted to maintain two implementations of the service in production, or two versions of the service interface in production."

"That's actually what I wanted to talk to you about. Now that we have a number of services that have multiple consumers, changes to those services could really become a problem. Maria's example is probably just the first of many to come. While we handled this one, I don't think having a facilitated session for every service change is going to scale well."

"I agree. This is a situation that we really haven't had to deal with much in the past. When our focus was solely applications, it was always the same set of end users that wanted to see some changes made. There was never a need to deal with multiple versions."

"I'd like for you to take this to the SOA Center of Excellence and have them come up with some recommendations around service versioning. Let's get ahead of this one before it becomes a problem."

The COE Tackles Service Versioning Policies

Elena met with Spencer later on in the day and relayed the conversation she had with the CIO. At the next meeting of the Center of Excellence, Spencer brought the team up to speed on the discussion between Andrea and Elena. He went through the efforts associated with Maria's Customer Information Service, and then asked the team for their thoughts.

The first person to comment was Jared, "I'm really surprised that this got Andrea's attention. I don't think any of the services that I've worked with yet have needed to be touched since version 1.0."

Another team member, Ron, concurred, "I agree. We've only had one service in my area that's had to be modified since its initial release, and in that case, it only had one consumer that moved in lock-step."

Raj countered these statements, "I have to disagree with you. In my area, we have at least five services that will be modified in the next six months. I think Andrea and Elena are right to have us look into this."

Spencer added, "Yes, remember, they didn't ask us to tell them whether there was a need to deal with versioning or not, they asked us to come up with some policies to ensure that when versioning does occur, we have some standard guidance on how to handle it."

Raj quickly offered his opinion, "I have some thoughts on this. Services are all about consumption, right? We've all said that a service is no good unless it can be consumed, right? Well, if that's the case, shouldn't we do whatever we can to accommodate service consumption? I think we shouldn't put a limit on the number of versions of a service interface that must be supported in production. In fact, I think we should make it a requirement that a service provider supports whatever interfaces are currently needed by its consumers. While my area is the one that has a number of changes coming, those changes tend to be driven by one consumer. Most of the other consumers don't change very often, probably even less frequently than when your services might change, Jared."

Jared countered, "Raj, I have to disagree with you. Trying to maintain a potentially limitless number of service interfaces would quickly become a nightmare for the service development team."

"But are you willing to sacrifice consumers for the sake of having a smaller number of interfaces to manage?" Raj asked.

Jared replied, "Remember, I've worked in the commercial software world before joining Advasco. The company I worked for had made so many different versions of our product to meet the specifications of our customers that we got ourselves in trouble. We had to make a change to a single capability, but due to all the branches that had been made in the code, the effort took months longer than it should have. As a result, we lost customers, not because we didn't make changes when they first came along, but because we had no ability to change quickly when a number of customers required the same modifications."

Raj responded, "I can see your point, however, I don't think that means the service providers can go to the opposite extreme and expect that consumers will incorporate whatever change they decide to throw out."

Spencer decided to interrupt the debate, "You've both raised two important, yet conflicting viewpoints. On the one hand, we have the service consumers. These consumers expect to have their demands met, and if there is an alternative path that meets those demands more quickly, they'll probably take it. This leads to a desire to bend over backwards to meet the demands of any consumer, even if it means having many, many versions of the service. On the other hand, we have the service providers. In order to provide good service, the team needs to keep the number of versions it provides to a minimum. While it's all managed by one team, we're really creating the exact same problem that we have today—the same logic being implemented in multiple places, and as a result, the time required to implement a change goes up."

He continued, "It seems that the thing we need to do is to come up with a policy that balances the needs of both the consumer and the provider. We clearly can't have an unlimited number of versions, but we also can't have just one version available."

Ron replied, "In the case of my area, we sometimes don't touch an application for 18 months."

Raj added, "My department is the same. I'd say that the majority of applications are only modified once every 12 to 18 months, with a few even longer than that."

Jared commented, "We have more turnover in my area. Just about everything gets released at least once a year. The few applications that don't, usually wind up getting decommissioned in the next year."

Spencer asked, "What's a realistic timeframe for service updates? In the case of the Customer Information Service, we almost went two full years without needing an update. I also know of at least two other services that have been updated every six months."

Raj replied, "Our services follow a similar pattern. I haven't seen anything that's updated more than twice a year. Some services are updated every nine months; some are updated every 12 or 15 months. There doesn't seem to be a standard pattern."

Spencer then said, "Let's look at this from a different perspective. Since it appears that all of our systems are updated at different intervals, let's instead look at what's realistic. We know maintaining one version of the service isn't enough. If we maintained two versions of the service, the worst case would be that the consumers only had six months to make their changes, presuming a new version was released every six months. If there were 18 months between versions, they'd have 18 months. If we maintained three versions of the service, the worst case now goes out to 12 months. If version 1 was in production, and version 2 was released in March, version 3 would be released in September, and then version 4 in March of the following year. That's also assuming that consumers aren't notified until the version goes live. What is more likely to happen is that version 2 would be announced early in the process. Realistically, a system using version 1 would probably have about 14 to 16 months to make their changes. For a service that is only updated every 18 months, we're now talking about three years or more to make the necessary changes."

Raj replied, "What if the service is updated every two months, or even more frequently than that?"

Spencer answered, "While it's certainly possible that a service could be updated more frequently, do we really think that the interface would change that frequently? I'm sure if we have projects that are updated that frequently, it is probably more likely to be bug fixes or other small changes that don't cause any change to the service interface. If the actual service interface does change that frequently, I think that the service team probably hasn't done a good job in seeking out potential consumers. They are probably being reactionary, and waiting for consumers to come to them. If we take the time to seek out consumers, we should be in a better position to avoid that scenario. On top of that, how many projects get completed in two months? If there were any, I wasn't involved in any of them."

Raj replied, "Yes, that's a good point. So, it sounds like three might be our magic number. Consumers wouldn't immediately have to jump to the new release, but they'd have at least one additional release cycle to acquire funding and staff to make the necessary changes."

Ron added, "I think we can live with this, but the one thing I want to be sure of is that changes aren't done in a vacuum. Just because there's a policy of three versions doesn't mean that all changes should be discussed with all existing consumers and new prospective consumers prior to committing to a release."

Spencer said, "Good point, Ron. If we don't communicate with each other, we're leaving ourselves open to problems and dealing with ‘he said/she said' scenarios."

With this caveat, everyone agreed that three supported versions was a good starting point. They all also agreed that the inconsistency in release schedules of applications could become a problem in the future. All of the members of the Center of Excellence knew of at least one application that was still in use in production, yet hadn't been modified in at least five years.

Spencer made sure he discussed this with Elena when he followed up with her the policy of three supported versions in production at one time. Elena and Spencer both agreed that having applications in use for over five years without anyone touching them was actually risky for the company, since all knowledge of the system could be lost to technology changes, personnel turnover, or other reasons. By keeping the policy at three supported versions of each service, it would encourage Advasco to review and, if necessary, refresh the systems on a more frequent basis, mitigating any risk associated with these long tenured applications.

Service Versioning Policies

In this article, Advasco runs into the challenge of modifying an existing service. While the initial version of a service is typically developed in lock step with one or more consumers, the hopes for synchronized schedules quickly fade away when a service has two or more consumers. As shown in the narrative, there are many different ways of addressing this challenge. What is consistent, however, is that the SOA governance effort must establish policies that are consistent with the behavior desired for the company's SOA efforts.

For at least two of the options presented in Spencer's original decision-making meeting for the Customer Information Service, attendees stated that a particular option would undermine the goals of the SOA effort. One option called for the annuity team to simply write their own version of the service that they would use. This went against the goal of having no two systems implementing the same logic. It also went against the goal of having a single owner for each service capability. Another option called for the service team to maintain an arbitrary number of service implementations. While this went along with the single ownership policy, it still ended up with multiple implementations of the same logic.

We were also presented with potentially conflicting goals. Having multiple versions of the service owned by a single team results in multiple implementations, but having a single implementation that was slow and difficult to change would go against the goals of agility for the organization. In the end, the Center of Excellence recognized that agility was the more important goal, and as long as the number of versions was kept to a small number, the associated overhead on the service team was worth it.

This example demonstrates a very important point. While an organization may initially set some very high level goals and behaviors, such as decreasing the time required to deliver new business capabilities by 10%, these goals must trickle down to finer-grained policies such as the number of services that will be maintained in production

Explicit or Implicit Versioning

When defining service versioning policies, one thing that must be considered is whether or not consumers are required to explicitly specify the version of a service that they will use or not. For example, when using a service that is accessed via HTTP, the service invocation must specify a URL. This applies whether the service requires a SOAP envelope or if the service is using a resource model provided via REST URLs. For Advasco, a URL used internally for a service will look like this:

In this example, there is no explicit version number associated with the URL. All we can infer is that the request is directed at the host named for a service at the path of /BooksRecords/Customer. In the case of Advasco, a URL naming standard enforced at a design checkpoint requires that the first portion of the path expresses the domain of the service, in this example, BooksRecords, while the second portion of the path expresses the service desired within the domain, in this example, Customer. If there were multiple versions of this service available, the version required for the request must be determined according to the identity associated with the request. Identity is normally passed through transport headers associated with the HTTP transport, or as part of the message itself. In the case of SOAP-based services, the message can contain both header elements and the message body. The WS-Security specification defines a standard location in the SOAP header for security credentials. For example, a SOAP request for a Customer Information Service may look like this:

<soap:Envelope xmlns:soap="" 

In this example, the namespace element of the message is At the end of the URI for the namespace, there is a month and date that can tell the recipient of the message that the schema used in this message corresponds to the November 2008 version of the Customer schema. It is entirely possible that even the namespace of the message may not contain an explicit version identifier; however, the version of the message can be determined by looking for the inclusion, or exclusion, of specific message elements.

Another example of a SOAP request could be the following:

<soap:Envelope xmlns:soap="" 
<wsse:Security xmlns:wsse="
<wsu:Timestamp xmlns:wsu="
<wsse:UsernameToken xmlns:wsu="
<wsse:Password Type="

In the above example, neither the URL for the request nor the XML namespace gives any indication of the version of the service desired. The only thing this message has is the identity of the consumer. This example uses the WS-Security UsernameToken profile and specifies a username of jdoe. Through the use of a service contract, this consumer can now be associated with a particular version of the service via policies. An intermediary can receive the message, check the policies associated with the contract for this consumer, and then either route to the appropriate endpoint or apply transformations to preserve backward compatibility.


Extending the Service Contract

The contract initially focused on providing a functional interface, along with a delivery schedule, if the service did not exist yet. However, there is much more to the service contract. The contract needs to also specify the policies that govern the run-time behavior of the service. In the example in this article, two run-time policies are required to enable the behavior that was described. The first is that the request needed to contain appropriate credentials to identify the source of the request. The second is that the request needs to be routed to a specific version of the service. While this may not seem important with the initial service implementation and its consumers, as soon as the next consumer comes along and requires a modification, as was the case in our example, this policy becomes very important

Policy-Driven Infrastructure

One reason for the formalization of the service contract is to allow the infrastructure to easily enforce the policies. First made popular in the context of web access management solutions, policy-driven infrastructure has four primary components as shown in the following figure:

Service VersioningService Versioning

The first component is the policy management point, also known as the policy administration point. This is where the administrator would enter the policies associated with the service contract. The policy management point would also be the place where management services would be exposed for data center automation opportunities.

The second component is the policy information point. This is the backing repository where policies entered via the policy management point are stored. When applied to SOA, the Service Registry/Repository can play the role of the policy information point.

Moving into the actual run-time path of requests, the third component is the policy enforcement point. This is where requests are intercepted and any applicable policies are enforced.

The final component, which is frequently co-located with the policy enforcement point, is the policy decision point. This is where the decision is taken on what to do when enforcing each policy.

To understand the relationship between a policy enforcement point and a policy decision point, consider a real world example. If you are driving a car and reach an intersection with traffic signals, you are at the policy enforcement point. All cars must pay attention to the state of the traffic signal to determine whether they can proceed in their desired direction or not. The traffic signal itself is the policy decision point. Based upon embedded sensors in the street or timers, the light is either red, amber, or green, which represents the decision on how to handle traffic from each direction. In this example, the policy enforcement point and the policy decision point are co-located.

Now, suppose you have driven your car to the entrance of a gated community. The gate, however, is unmanned. Instead, there is either a video camera or an intercom at the gate. The gate represents the policy enforcement point. The policy decision point, however, is not at the gate. The policy decision point is wherever the security personnel is sitting watching the feed from the camera or listening to the audio from the intercom.

Putting this in the context of our versioning example, a request from a service consumer would be intercepted by the policy enforcement point. The policy enforcement point would extract the message content, and hand it off to a policy decision point. The policy decision point would examine all applicable policies for the service requested from the policy information point. There will be some policies that are universally applied, such as requiring that some form of identity be on all service requests. From that point, the identity can be authenticated and authorized, according to the policies in the service contract. Once identity is established, policies that may be specific to the service contract between the specific consumer associated with the identity provided and the service being requested can be enforced, such as what version of the service should receive the request, and whether any of the transformations will be applied. All of these policies should already be in the policy information point as a result of previous actions by an administrator via the policy management point.

Mapping this conceptual approach to the actual infrastructure associated with your SOA efforts typically takes one of the following two forms, or a combination of the two.

Service Versioning

The above model is a gateway-based approach (or brokered gateway pattern). A service consumer never interacts directly with a service provider; rather the request is first directed through a gateway that is responsible for policy enforcement and policy decisions. More often than not, the gateway also maintains a cache of policies locally to avoid having to establish a connection with the policy management point for every service request. The management console for the service gateway is the policy management point. This will include some form of backing stores for the policies.

Service Versioning

The other model shown above is a agent-based model, an agent is deployed on the service provider platform. This agent is typically configured as part of the platform configuration and not as part of the actual service. The agent plays the exact same role as a service gateway, with the only difference being that it performs its logic in the same execution thread as the actual service, should the policies allow the request to be processed.

While these two diagrams represent two common approaches, individual vendor products in this space can take different architectural approaches. Some may externalize the policy decision point, changing the role of the cache to be a decision cache, rather than a policy cache. Some may utilize a service registry/repository for the policy store; others may require the use of a dedicated database. Some products may include both gateways and agents, and some may even include consumer-side agents in addition to the more typical provider-side agents.

Applying Policy

In order to enforce the two policies mentioned earlier, which were:

  1. All requests must contain appropriate credentials to identify the source ofthe request.
  2. Based on the source identified, requests must be routed to the appropriate version of the service.

the basic operations would be:

  1. In the policy management point, configure a policy for the service endpoint that applies to all consumers which states that only requests that contain credentials in the format desired will be allowed. Any request that does not contain credentials, or contains credentials in the wrong format will be rejected
  2. In the policy management point, for each authorized consumer, define a policy that routes the request to the appropriate endpoint or applies appropriate transformations to the incoming request and outgoing response.

The policy enforcement approach can be thought of as a pipeline of decisions, ultimately resulting in a rejection of the request or the correct routing to the appropriate endpoint. Visually depicted, it looks like this:

Service Versioning

There are a number of different categories of vendor products that are capable of providing this concept of policy driven infrastructure, providing a platform for the implementation of the policy pipeline as seen in the preceding figure.

Enterprise Service Bus

Perhaps the most common of the categories, the Enterprise Service Bus, or ESB, is considered by many to be "the technology" associated with SOA adoption. In reality, an ESB is just one way of providing the capabilities associated with consumers and providers.

There is no standard architecture for an ESB. Some vendors use a gateway-based approach exclusively, others are exclusively agent-based architecture, and others provide both. The one common thing in all of them is that the ESB represents the policy enforcement point. Enterprises that have adopted ESB technologies typically require that all requests go through it, and take measures to ensure that requests which are not sent through the ESB are not allowed.

The biggest risk that an organization may face with an ESB is that many of these products are targeted at developers. As a result, the separation of policies, or even the notion of a policy itself, may not be as clear as with other solutions. This will certainly vary by vendor; therefore, an analysis of the conceptual model of the product should be part of your evaluation process.

XML Appliances

A second category of products that can provide this policy-driven infrastructure is XML appliances. These products primarily started in the XML acceleration space, expanded into perimeter security for XML over HTTP transactions, and now provide broader capabilities for additional policy domains associated with service connectivity. Some vendors are now marketing their appliances as ESBs.

Being appliances, these products typically adhere to a gateway-based model, although some of the vendors in this space create appliances by placing software on a commodity hardware platform. Those that have taken this approach may have the ability to repackage the software for installation as an agent.

The XML appliances are less likely to have a developer-centric operating model. They are more likely to present an operational model that is targeted towards an operations team rather than a development team, although just as with ESBs, there is significant variability from vendor to vendor.

Service Management Platforms

The next category of products in the space of policy-driven infrastructure is the service management platform. Unlike the typical systems management product, which normally observes system behavior in the background, products in the service management space take a more active role. In addition to collecting metrics about service invocations, they can also intercept requests and enforce policies associated with those invocations.

Service management products from the major vendors in the space will include both gateways and agents, as well as agents for other gateways, such as ESBs or XML appliances, as if this space wasn't confusing enough. A key difference between service management platforms, ESBs, and XML appliances is typically in the policy domains supported. For all of these products, the policy domains usually include ones focused on individual requests, such as security, but where the service management platforms really shine is in policies that apply across multiple requests, or policies that are consumer-based, rather than service-based. For example, service management platforms will typically be able to enforce a policy that mandates notifications whenever the average response time for a specific time period exceeds a particular threshold. Taking this concept a step further, a service management platform should also be able to apply different thresholds for different consumers. Beyond policy enforcement, service management platforms also include advanced capabilities in collecting metrics on service traffic, along with sophisticated dashboards, reports, and analytics capabilities on those metrics. In contrast, a service management platform may not have as sophisticated routing capabilities of an ESB or the raw performance or threat protection capabilities of an XML appliance.

Service Invocation and Exposure Frameworks

The final category that must be included is frameworks, specifically service invocation and exposure frameworks. As mentioned earlier, a gateway is not required to implement policy-driven infrastructure. A service invocation framework can be used to intercept outgoing requests and perform policy enforcement and decision-making, and a service exposure framework can be used to intercept incoming requests and perform policy enforcement and decision-making. For example, in the domain of security policies, a service exposure framework such as .NET and Windows Communication Foundation or Java EE and JAX-WS, allow security policies to be specified in an external file from the actual service implementation code.

Many of these frameworks have also extended the normal WSDL (Web Services Description Language) to specify policies for using the service, such as what type of security credentials are required. These policies are normally specified using the WS-Policy framework, but beyond security (WS-SecurityPolicy), and reliable messaging (WS-ReliableMessagingPolicy), additional standards for specifying policies have not been created. By including these policies within a WSDL document, a consumer can ensure the messages they send are compliant with what the provider expects.

The primary drawback to utilizing frameworks, and also common to an exclusively agent-based approach, is that it limits the domains of policies that can be enforced. In this article, the key focus was service versioning. This is an area where a framework-based approach may be insufficient. The reason is that by the time we reach the policy enforcement point, we are already executing a particular version of the service. At that point, it is too late to redirect the request to a different version, unless the versioning logic is coded into the service itself. Agents may have a bit more flexibility in this area, but if the versions aren't running in the same application server or application server cluster, there may still be challenges.

Conceptual View

While not required, it is possible to combine all of these elements into a single view. XML appliances, with their advanced security capabilities, excel at the perimeter, ESBs with their mediation and routing capabilities can act as a centralized broker, and Web Service Management agents can be leveraged throughout. Combined with the core Web Services and XML support provided by a framework yields the following conceptual view. Policy enforcement and decision points are labeled with PEP/PDP, policy information points are labeled with PIP, and policy management points are labeled with PMP.

Service Versioning

Service Lifecycle Management

The ability to enforce policies at run time is very important to SOA. In our example, the need to do this was introduced when the Center of Excellence determined that organizations managing the service must support up to three versions in production. Keeping in line with the definition of governance, the Center of Excellence recognized that the desired behavior was to support the changing needs of consumers while not overburdening the team providing the service. Remember, however, that governance is about people, policies, and process. In this case, the policy exists, but to ensure things are successful, appropriate processes must be put in place. This process is service lifecycle management.

Consider how our example could get worse, despite the policy that was put in place by the Center of Excellence. There were several assumptions that were made by the Center of Excellence in coming up with the policy, largely around the frequency of changes that would be necessary for a service, or a consumer. As an organization embraces SOA, the number of interdependencies between systems will increase. Previously, organizations may have only updated applications every 12 to 18 months, and those updates were self-contained to the application itself. Now, due to the increased number of interdependencies, those updates may involve other components outside of the application's direct control. Look across many applications, and the possibility exists that a service gets one request for a change every month for four months straight, and then a period of no changes for several months.

In order to mitigate this, an organization must change the way that these changes are managed. As a point of comparison, let's look at the interaction that organizations have with their technology vendors. When an organization runs into a bug, or requests a new feature, it normally isn't delivered on its own. Rather, the vendor maps the feature request to their release schedule, and delivers it as part of a collection of features and bug fixes that were requested by a variety of customers. If an organization doesn't adopt a similar approach for its internal development efforts, they run a risk of being crippled by the interdependencies that were intended to increase agility, not stifle it.

Service lifecycle management takes a product management approach to services. Rather than viewing service development as a project that ends when the service is placed into production, the lifecycle of a service needs to be viewed as a process of continual change and improvements, each one occurring through a managed release. This can be a difficult concept to grasp when an organization is used to thinking only in terms of projects.

The typical project, when viewed in the large sense, involves an analysis and definition phase that refines the scope of the effort, a design and development phase, a testing and debugging phase, and finally, deployment into production. The project begins when funding is approved, and ends when the solution is deployed into production and accepted by the sponsors. This effort is linear, with a clear beginning and end, as shown here.

Service Versioning

Interestingly, the project does not include any effort to monitor and manage the solution after it goes into the production. While the project may put these processes in place, if there are changes required based upon production monitoring, the project team is no longer in place to address it. A support team may exist, but these teams are normally focused on bug fixes and troubleshooting, at most. The resources that are needed to make incremental changes are more than likely assigned to new efforts.

A product management-based approach no longer views things in terms of a single linear effort with a clear beginning and end. Rather than being based on the project, the lifecycle is based on the product. The lifecycle begins when the need for version one is identified and funded, and ends when the last remaining version is decommissioned from production. In between those two events, there are any number of releases, each having the characteristics of the typical project: analysis and definition, design and development, testing, and deployment. The missing elements that tie it all together are the three M's: monitoring, management, and marketing as shown in the following figure:

Service Versioning

These three M's are critical to getting out of the habit of linear projects and into the world of product management


The first of the three M's is monitoring. Clearly, most organizations have monitoring in place. Normally, this monitoring is focused on up/down behavior. Is the solution up and running, or is something wrong that needs to be fixed? This type of monitoring is very reactionary, and solely concerned with the behavior when something goes wrong, and not at all concerned with the behavior when things are running normally. When performing service monitoring, the focus needs to shift from the internal operations of the service to an external viewpoint on the behavior of the service. What is the response time being seen by consumers? How does the response time vary during the day? How is the response time changing over a week, a month, or several months? By observing the behavior when things are working normally, a service manager can take a very proactive approach, not only to problem detection and resolution, but also to anticipating future needs


The second M is management. Monitoring of the service is typically an activity only performed by the service provider. In order to truly be proactive, a service manager must take that information and discuss it with their service consumers. If the monitoring indicates some level of unusual behavior, be it a slow, but steady increase in response time, or anomalies in usage patterns, the service manager must discuss it with the consumers to determine the root cause. It is in these discussions that new feature requests may arise, changes being made to the existing interface in order to better support the usage patterns, or even changes being made to the consumer, based upon the observations that have been made.


The final M is marketing. Management is focused on existing consumers. Marketing is focused on new consumers. Many organizations take a "build it and they will come" approach, and all too often find out that nobody comes. While governance certainly plays a role in trying to ensure that projects find the services that they need for their solution, service providers should not rely solely on governance for finding new consumers. A service manager must take an active role in marketing the capabilities available.

As these activities continue, the service manager can now begin forming plans for the next release in a proactive manner, rather than waiting to begin the cycle until the next consumer comes along and requests it. If a service manager is successful in these efforts, they can begin to plan out scheduled releases on a regular basis. This is the key to effective version management. If consumers know that a new release will be produced and deployed every six months, they can plan their own releases around that effort. If, instead, releases occur on an ad hoc basis, it is far more difficult for an existing consumer to respond to those changes.


In this article, Advasco was faced with the challenge of service versioning. A new consumer had requested some changes to the Customer Information Service, but the existing consumers could not accommodate the changes necessary in the timeframe required. Led by the SOA Center of Excellence, a decision-making process was used to determine the best course of action, which was to support both the old interface and the new interface, either by deploying two versions of the service, or leveraging transformations in the middle to ensure backward compatibility.

While this solved the situation for the Customer Information Service, the CIO was concerned that this would not be the end of the versioning debate. The Center of Excellence debated this and introduced a policy that balanced the needs of the service consumers with the needs of the team providing the service. The policy was to support up to three versions of a service in production.

Service versioning is a very important issue for an enterprise to deal with in order to achieve the agility goals desired. If policies are not established, contention will arise. It can be between individual consumers of the same service, or between consumers and the service provider.

The need to support multiple versions also introduces the role of policy-driven infrastructure in a run-time environment. If multiple versions of the service are deployed simultaneously, there must be a mechanism for routing requests from specific consumers to specific versions of the service. The version desired could be explicitly specified as part of the request, or the service contract can be used to define a policy that can be implicitly enforced by the run-time infrastructure.

Policy-driven infrastructure has four key components. First, a policy management point allows policies to be administered. Second, a policy information point allows policies to be stored and retrieved. Third, a policy enforcement point exists in the run-time path of the request, intercepting it to allow policies to be enforced. Finally, a policy decision point is where decisions are made based upon the message content and the policies that are applicable to the interchange at hand.

Examples of policy-driven infrastructure include the ESB, XML appliances, service management platforms, and service frameworks.

However, policies and infrastructure alone may not allow versions to be easily managed. By changing the culture of the organization from one that deals with change on an ad hoc basis to one that anticipates change, versioning can be managed much easier.

Organizations today typically provide technology capabilities through the use of projects. A project lifecycle has a clear beginning and end, but the solutions produced by those projects do not. This creates a mismatch when a solution needs to change, because a new project with potentially new staff must be justified, funded, and completed.

An alternative to the typical project-based thinking is to embrace service lifecycle management. Service lifecycle management encourages service teams to view their service as a continual sequence of refinements, with the lifecycle rooted not in the project timeline, but the service's timeline. It begins when version 1 is approved and funded, and ends when the last remaining version of the service is decommissioned from production. The key difference in this approach is between the time a service is deployed into production and the time the next release begins, the service team must focus on monitoring, management, and marketing. Monitoring records the behavior of the system, beyond simple up/down monitoring, management utilizes the data collected by the monitors to increase the understanding of the system behavior by both the service provider and the service consumers. Marketing is focused on finding new consumers in a proactive manner, rather than relying solely on the staff of new projects to properly search the service registry and repository.

By practicing good service lifecycle management, a service team can determine the appropriate timeframe for its releases. Jenterprises prefer when their major technology vendors provide updates on a regular basis, so should an enterprise's internal service providers schedule their updates. By providing new versions on a regular basis, there will be no surprises for the existing consumers when changes are announced.

You've been reading an excerpt of:

SOA Governance

Explore Title