15 min read

(For more resources related to this topic, see here.)

Service stages

A service goes through several stages; it has a life cycle. The following figure shows the various stages of this life cycle:

Apart from identifying, designing, and implementing a service, you also need to take into account the possibility of cleaning up services. Services can become obsolete, because they don’t conform to the requirements anymore, because there are better alternatives or because nobody is using them anymore. The stages deprecated and retired are used for this. The following table explains the different life cycle stages of a service and who is involved in reaching that stage.

Stage

Description

Role

Identified

The service is identified; the organization is aware that it is needed. The approach to identification can be either top-down, bottom-up, or meet in the middle.

Architect: Top-down (and meeting the middle) identification of service is based on the process or user interface requirements.

Developer: Bottom-up identification is based on the existing capabilities.

Designed

The service interface (operations) and contract are known and documented. A developer can create a mockup of the service based on the design by tooling, and clients can be built based on the design.

Architect: Top-down design of services based on the process or user interface requirements.

Developer: Bottom-up (and meet in the middle) design based on existing capabilities.

Implemented

The service is available for consumers to use in production systems.

Project, or the service is bought from a supplier.

Administrator: Deploy the service and makes it available.

Deprecated

The service is a candidate for replacement or is obsolete. Current consumers can keep using the service for now; new consumers should use a replacement or find other alternatives.

Service provider: Decides to move to this state.

Retired

The service is no longer available for consumers.

Service provider decides and the administrator undeploys the service.

There are no approval states in this life cycle. Within your organization you need to decide who is responsible for what type of actions and who needs to approve those. For example, you could decide that since you have already created a business case for the realization of the SOA, you don’t need to approve identified services explicitly. If something is identified and later you decide you don’t need it after all, you can either delete it, or retire it straight away. Another approach is to approve the services in the step define the solution in detail, as part of the approval of the project architecture.

Keep details out of the life cycle

Beware of adding too many details of the software development and release management in the life cycle of the services. It becomes tedious and outdated very quickly. The only message it needs to convey to the service consumers is, can these services still be used?

Versioning of services

During the life cycle of a service, the service changes because consumers have change requests, laws and regulations change, and errors need to be fixed. First, you learn about versioning of services, and then the relationship with the different stages of a service is investigated. A common way of keeping track of these changes is using version control. Version control is the management of changes to documents, software, and artifacts. Changes are identified by a number or letter code; a version or revision number. Now when do you give your document, data model, or service a new version number? And what type of versioning scheme are you going to apply? Usually, you make a distinction between minor and major versions of a change. A service consists of an interface, a contract, and an implementation. All these aspects of a service can change. Let’s look into the different types of change and how this affects the version of your services.

Type of change – contract, interface, and implementation

Let’s take the example of a diner that offers breakfast. The menu lists all their services. The contract of the service states the quality, price, availability, order time, and so on. The interface is the way we interact with a service. When ordering breakfast we interact with Jane, our waitress, and the menu that is in English and Spanish. The implementation of the service is the cooking of the service, and the serving and eating of it.

Changing the contract

The contract of the service states:

  • Ingredients are all local and natural

  • Breakfast might contain gluten

  • Breakfast can be ordered from 7 a.m. to 1 p.m.

  • Breakfast costs $9.95

  • Payment by credit card or cash is accepted

  • Currency that is accepted is in dollars

  • Time between ordering breakfast and the delivery time to the table is 5 minutes to 10 minutes

  • Complaints should be delivered to the manager by telephone

Prices of the ingredients increase every year, so after the first year the breakfast place is in business, the cost of the breakfast is increased. This is a major change in the contract, so the owner creates a new menu with the new prices, effectively creating a new version of the service.

The waitress informs the regulars (customers that visit the diner every week) about the increase in advance. Other customers find out when they visit the breakfast place.

After having been in business for a couple of years, the owner of the breakfast place notices that a lot of tourists from Europe and Asia visit his breakfast place. They are suffering from jet lag and have different breakfast requirements. They would rather have something light and pay less for the breakfast. The manager decides to change something in the contract: not all breakfasts cost the same anymore; it depends on what you order. Now this is good news for customers who want to eat less: they don’t have to pay for something they did not order. However, existing customers who were used to the “all inclusive” breakfast concept and eat more won’t appreciate the change.

Obviously, the owner also has other options, not just changing the service for everyone at once:

  • Change the contract for everyone, everybody pays a la carte

  • Add the “light” breakfast option to the menu as an additional menu for a fixed lower price of $4.95

  • Offer an a la carte option next to the all-inclusive breakfast

After some research, he decides to use the last option, in effect leaving the old contract intact by adding an a la carte option to it.

Note that in both examples nothing has changed about the interface, you still order what you want to eat for breakfast, and the implementation has not changed either. The same cook is preparing the breakfast, the same ingredients and kitchen utensils are used, the same cooking method is applied, and so on. The change was in the contract of the service. The first change (increase in price) affected all the customers in the same way. The second change was more complicated, it was an improvement for some customers but the owner did not want to scare away the other group. Obviously, the owner does not use version numbers in his menu, but he did create a new version of the menu. The way this was communicated was not with a version number but with an effective date and an announcement to the customers.

Changing the interface

Apart from the contract, the interface can also change. As you have read before, a lot of customers are from Europe and Asia. For these people, it is sometimes hard to speak English. So the owner of the diner decides to print the menu in multiple languages: Spanish, French, Japanese, and Chinese. He also hires some waitresses and waiters that speak multiple languages.

This change has no impact on the current customers; English is still supported as a language to order the breakfast in.

After a while, the waitress who speaks French quits her job and the owner decides not to replace her, because only a small number of customers speak French. This change has an impact on the current customers who speak French; they will have to switch to another language that still is supported.

Changing the implementation

After a couple of years, the owner of the diner decides to hire some new kitchen staff and replace some of the kitchen tools. The new people improve some of the processes in the kitchen, thus creating a more efficient operation. The customers notice that a dish is served a little faster than in the past and that fewer meals arrive cold or over-cooked as a result of the improved operation.

Versioning schemes

You want to keep track of changes to a service, using version control. You don’t want service consumers to accidently use the wrong version. This can cost money or cause errors to occur. In the case of an IT service, you don’t want to break the code of the service consumers. The types of change that can occur in the BreakfastService also apply to IT services; you can change the interface, the implementation, or the contract.

The service as a whole is the unit of interest for the service consumer; therefore you need to version the service as a whole. This means that you change the version of the service if any of the parts of a service change, whether this is the implementation, the interface, and/or the contract. As a consequence, there is no need to version the contract, interface or implementation separately.

Version the service as a whole

Version the service as a whole and you need to version the underlying files. There is no need to version the contract, interface and implementation separately.

The following diagram illustrates this for OrderService. Every time a change is made to a file, this is recorded in the version control system. This has no impact on the version of the service. Once you decide to release the change into production, you determine the new version of the service as a whole.

The diagram shows OrderService with a version 1.0.1. It consists of an implementation, contract, and an interface. These are not versioned separately, because this is of no interest to the consumer. Three Java files make up the implementation. These are versioned in the version control system, because the service provider needs to keep track of the changes they make. The contract consists of two policy files: a security policy and an availability policy. These are versioned in the version control system as well. The interface consists of an XSD and a WSDL. These are versioned in the version control system.

Versioning and life cycle stages

There are several things you can do when the version of a service changes, as you learned with the change of contract of BreakfastService:

  • You can replace the current version with the new version

  • Let the new and current (or old) version co-exist (for a limited time period)

Apart from deciding what to do with the old version, you also have to decide what to do with the version number. This depends on the impact of the change; to determine whether a change is minor or major, you have to look at the impact the change has on its current consumers. For example, adding an operation or a field has little impact on current consumers. If you want to make a major change, it is good practice to create a new major version of the service, and to support consumers who want to keep using the previous (deprecated) service for a certain time period.

The following table shows a common versioning scheme that works well for both consumers and providers:

Change type

Minor version

Major version

Previous version

Major change

To 0

Increase by 1

Keep it (stage is

deprecated)

Minor change

Increase by 1

Stays the same

Replace it (stage stays implemented)

Let’s look at an example; suppose your organization offers OrderService and uses the convention [major version].[major version].[minor version]. The current version is 1.0.0. This means the major version is 1.0 and the minor version is .0.

Now if you make a major change, you increase the major version and keep the previous version available to consumers for a little while. This results in two services:

  • OrderService 1.0.0 (stage deprecated with a planned end date)

  • OrderService 1.1.0 (stage implemented)

If the change is minor, you increase the minor version and discard the previous version. This results in one service:

  • OrderService 1.0.1 (stage implemented)

Supporting two versions has advantages for both the consumers and for the providers. Consumers can plan the migration to the new version, and planning the upgrade for the provider is also a little easier because not everybody needs to test the new service at the same time.

Note that you will keep track of all the files that you use during development in your version control system. The version number that is of interest here is the version number that you communicate as a whole to the service consumers when the (new version of the) service is released.

Making the version explicit for service consumers

When you are using a WSDL to describe your interface to your consumers, you can make the version of the service explicit by putting the (major) version number in the namespace and in its endpoint.

A namespace in a WSDL or XSD is used to differentiate between elements, and it enables the document to reference multiple external specifications, including the WSDL specification, the SOAP specification, and the XML Schema specification.

By using the version in the endpoint, it is also easier to support two versions of the same service on your server.

Let’s see how this works with a WSDL for OrderService:

<wsdl:definitions name="OrderService-1.0"
targetNamespace="http://vennster.nl/CRM/OrderService-1.0"

 


<wsdl:documentation>
The Order will create an order for multiple orders
Version history
V1.0.0 Initial service description
</wsdl:documentation>
<wsdl:types>
</wsdl:types>
<wsdl:message>
…
</wsdl:message>
<wsdl:portType>
..
</wsdl:portType>
<wsdl:binding>
…
</wsdl:binding>
<wsld:service name=OrderService-1.0
<wsdl:port name="OrderServicePort"
binding="tns:OrderServiceSoapHttpBinding">
<soap:address location="http://vennster.nl/CRM/OrderService-1.0"/>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>

The highlighted parts show the version in the namespace and in the endpoint (soap:address). In this case, the major version is in the namespace (1.0 and the endpoint); the minor version is in the documentation (1.0.0).

With REST services you can make a distinction between versions in a similar way. Basically you have two options:

Multipurpose Internet Mail Extensions (MIME) are used to identify the type of representation that is in the body of an HTTP request or HTTP response. MIME types are sometimes referred to as CONTENT-TYPES. The MIME type has a major type and a subtype, separated by a slash.

The major MIME types are text, video, image, audio, and application. Application can refer to a number of formats: application/xml, application/pdf, application/octet-stream, and so on. For vendor specific commercial use, vnd is used as a prefix, followed by the name of the company and the domain for example, application/vnd.vennster.crm. For personal non-commercial use, prs is often used. For experimental or non-standard types you can use x.

Putting the version in the vendor MIME media type, has the disadvantage that user agents such as browsers, wget, and so on don’t understand the MIME type. So you might not be able to display the resource correctly. The advantage of putting the version in the MIME type is that it has less impact on the client code.

To make the version explicit in a service, you can implement an operation getVersion that returns the version of the service (both the major and the minor version). This operation can also be used as a heartbeat operation by monitoring tools.

Versioning tips

Support the current version and the previous version in case of a major change.

Use major and minor versions. Minor versions can be put in the documentation. Major versions can be expressed in the namespace and endpoint in case of WSDL or in URI, or MIME type in case of REST. Implement a getVersion method in your service.

Communicating change

In the previous paragraph, you learned what type of change could occur in a service and what versioning schemes you can apply. These changes have some impact on the customers or service consumers. To make sure that service consumers can adjust to the new version of the service, you have to take the following steps:

  • Determine if the change is major or minor

  • If the change is major:

    • Change the state of the service to deprecated and determine the “end of life” date;

    • Create a new version of the service with the state identified

    • Announce the change to all current clients

    • Design the new version of the service and change the state of the new service to designed

    • Communicate the new design to clients who want to migrate

    • Realize the new version of the service and change the state to implemented

    • When the “end of life” date is reached, remove the old version

  • If the change is minor:

    • Design the new minor version of the service

    • Announce the change to all current clients

    • Realize the new version of the service

  • Communicate the situation to all current clients and prospects that have indicated interest in the service

There are different ways of communicating these changes to your clients: you can announce it in a meeting, you can send emails, or you can update a central registry that describes all the available services.

Changing the namespace and endpoint of the service is a good way of communicating the change at runtime. The client calls a service using the namespace in its code, as you can see in the Java example given as follows:

public class OrderServiceClient{
public static void main(String[] args) throws Exception {
URL url = new URL("http://vennster.nl/CRM/OrderService-1.0?wsdl");
QName qname = new QName("http://vennster.nl/CRM/OrderService-1.0/",
"OrderService-1.0");
Service service = Service.create(url, qname);
OrderService orderService = service.getPort(OrderService.class);
System.out.println(orderService.orderProduct("ipod"));
}
}

Now let’s look at tooling support for versioning and life cycle management.

Packt

LEAVE A REPLY

Please enter your comment!
Please enter your name here