Chapter 5. Web-Based Service Technologies
The lack of interoperability between evolving technology platforms, particularly between the Microsoft .NET and Java technology stacks, initiated the conception of the Web services standards. Interoperability between services is fundamental to an SOA, underpinning all aspects of the service-orientation paradigm. Web-based service technologies have established industry standards and conventions for realizing baseline interoperability.
Note
The term “Web-based services” includes both SOAP and REST-style services. The terms “SOAP-based Web service” or simply “Web service” are used to refer to Web services that rely on the use of SOAP and WSDL.
Note
This chapter provides concise introductions to the technology and syntax of SOAP-based Web services and REST services that are by no means comprehensive tutorials. If you are new to Web-based service programming, it is recommended that you study the following two series titles:
• Web Service Contract Design & Versioning for SOA
• SOA with REST: Principles, Patterns & Constraints for Building Enterprise Solutions with REST
These books teach the programming and architecture behind Web-based service technology specifically within the context of SOA and service-orientation principles.
Alternatively, if you are already experienced with the use of Web-based service technologies, you can skip this chapter entirely.
5.1 SOAP-Based Web Services
SOAP is a messaging standard specifying how data is encoded “on the wire” when passing between services. Initially defined as an acronym for “Simple Object Access Protocol,” the description failed to encompass the subject matter of the standard. Therefore, “Simple Object Access Protocol” was dropped and SOAP was retained. SOAP defines the encoding of service requests and responses as XML documents.
SOAP-based Web services rely heavily on the use of the Web Services Description Language (WSDL), which provides the means of expressing the service contract as a collection of operations with associated request/response messages. Also relevant to SOAP-based Web services, especially from a historical perspective, is the Universal Description, Discovery, and Integration (UDDI) industry standard that was originally conceived as a “Universal Business Registry” that would support the dynamic discovery of e-commerce services. A public UDDI directory was maintained jointly by IBM, Microsoft, and SAP until 2005. For our purposes, UDDI can be considered as a standard for directories storing categorized descriptions of services that can be programmatically accessed.
A Web service’s capabilities are described in a WSDL definition, which defines the contract for and utilizes the functionality exposed by the service. A WSDL definition describes a service as a collection of port types or interfaces, each of which comprised of as a number of operations.
Each operation has associated input and output messages that comprise one or more “parts” of different “types.” Exceptions are handled by throwing faults also defined within the WSDL document. Faults provide an abstract definition, also known as an abstract WSDL, of the service interface independent of technology concerns, such as the protocol used to invoke the service. The content of messages is specified as types, which can either be defined within the WSDL document or in a separate XML schema referenced via the XML schema import element.
Required to call the service, the service endpoint and transport protocol exposing the service are specified in the concrete implementation section of the WSDL using the service and binding elements. The service element identifies a collection of endpoints (ports) exposed with a particular binding. The binding element binds the service to a physical implementation, specifying data type and protocol mapping.
The following code presented in Example 5.1 employs a single port type, port, and request/response operation with messages defined in a separate schema imported and referenced within the WSDL document. Specifically, it shows the WSDL document describing the Account Enquiry service, which returns a customer’s balance and available funds using the account and branch number to identify the account. The data types are indicated as XML complex types, which are defined in a separate schema referenced within the WSDL document.
<?xml version="1.0" encoding="UTF-8"?>
<definitions name="AccountDetails" targetNamespace="http://com.
example.services.personalbanking/AccountDetails/"
xmlns=http://schemas.xmlsoap.org/wsdl/ xmlns:wsdl="http://schemas.
xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="http://com.example.services.personalbanking/
AccountDetails/" xmlns:ns1="http://com.example.services.
personalbanking/AccountDetails">
<types>
<xsd:schema targetNamespace="http://com.example.services.
personalbanking/AccountDetails/" xmlns:ns1="http://com.example.
services.personalbanking/AccountDetails">
<xsd:import namespace="http://com.example.services.
personalbanking/AccountDetails"
schemaLocation="AccountDetails.xsd"/>
<xsd:element name="AccountId" type="ns1:AccountId" />
<xsd:element name="AccountInformation"
type="ns1:AccountInformation" />
</xsd:schema>
</types>
<message name="GetAccountInformationRequest">
<part name="AccountId" element="tns:AccountId"/>
</message>
<message name="GetAccountInformationReply">
<part name="AccountInformation" element="tns:AccountInformation"/>
</message>
<portType name="AccountEnquiry">
<operation name="GetAccountInformation">
<input name="input1"
message="tns:GetAccountInformationRequest"/>
<output name="output1"
message="tns:GetAccountInformationReply"/>
</operation>
</portType>
<binding name="AccountDetailsBinding" type="tns:AccountEnquiry">
<soap:binding style="document" transport="http://schemas.xmlsoap.
org/soap/http"/>
<operation name="GetAccountInformation">
<soap:operation/>
<input name="input1">
<soap:body use="literal" namespace="http://com.example.
services.personalbanking/AccountDetails/"/>
</input>
<output name="output1">
<soap:body use="literal" namespace="http://com.example.
services.personalbanking/AccountDetails/"/>
</output>
</operation>
</binding>
<service name="AccountDetailsService">
<port name="AccountDetailsPort"
binding="tns:AccountDetailsBinding">
<soap:address location="http://localhost:18181/
AccountDetailsService/AccountDetailsPort"/>
</port>
</service>
</definitions>
Example 5.1 The data types referenced in Example 5.1 are defined in Example 5.2, which provides the XML schema definition for the Account Details service.
AccountDetails.xsd
<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://com.example.services.personalbanking/
AccountDetails" xmlns:tns="http://com.example.services.
personalbanking/AccountDetails" elementFormDefault="qualified">
<complexType name="AccountId">
<sequence>
<element name="AccountNumber" type="string" />
<element name="BranchNumber" type="string" />
</sequence>
</complexType>
<complexType name="AccountInformation">
<sequence>
<element name="AccountBalance" type="float" />
<element name="AvailableFunds" type="float" />
</sequence>
</complexType>
</schema>
All WSDL documents have the same basic structure and contents but the details can vary. Although Examples 5.1 and 5.2 show the interface, service, and binding together in a single WSDL document, splitting them into separate interdependent documents is also possible. Some implementation tools can handle the separation of WSDL files, although not all tools deal with separate WSDL files correctly. A single document is commonly used to aid interoperability.
Under the SOAP standard, a SOAP message consists of zero or more SOAP headers followed by one SOAP body. The body contains the message data intended for the service implementation. The headers provide a means of passing service metadata, such as processing directives, targeted at the Web services runtime rather than the service implementation. A broad variety of information related to the processing of SOAP messages can be carried by the header to facilitate interoperability between services.
A sample request/response message sent to the Account Enquiry service is shown in Examples 5.3 and 5.4. The GetAccountInformation request is a request/response operation that exchanges messages with the service consumer.
<?xml version="1.0" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/
envelope/">
<SOAP-ENV:Body>
<ns1:AccountId xmlns:ns1="http://com.example.services.pers
onalbanking/AccountDetails/">
<ns1:AccountNumberxmlns:ns1="http://com.example.services
personalbanking/AccountDetails">101049</ns1:AccountNumber>
<ns1:BranchNumberxmlns:ns1="http://com.example.services
personalbanking/AccountDetails">2155</ns1:BranchNumber>
</ns1:AccountId>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<?xml version="1.0" ?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/
soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:ns1="http://com.example.services.personalbanking/
AccountDetails" xmlns:ns2="http://com.example.services.
personalbanking/AccountDetails/">
<soapenv:Body>
<ns2:AccountInformation>
<ns1:AccountBalance>100.0</ns1:AccountBalance>
<ns1:AvailableFunds>100.0</ns1:AvailableFunds>
</ns2:AccountInformation>
</soapenv:Body>
</soapenv:Envelope>
The SOAP over WSDL standards allow for two different styles of SOAP messaging, known as remote procedure calls (RPC) and literal style. RPC style is based on the premise that a SOAP message is a means of invoking a remote operation. In the case of the Account Details service, the root element of the SOAP body identifies the operation invoked and contains the request/response data. The root element of the SOAP body helps the Web services environment determine the operation invoked at runtime and dispatches the message to the appropriate method of the service implementation. Alternatively, the literal or “document” style is based on a view of services exchanging documents rather than invoking remote operations.
Traditionally, Java Web Service implementations favored RPC-style Web services, and Microsoft favored document style. Document-style SOAP messages further specify an operation name as the root element of the body in the same way as an RPC-style message. For wrapped document style, messages appear the same “on the wire” as those corresponding to an RPC-style service with matching operation names. Wrapped document-style services are preferred for being highly interoperable. The inclusion of the operation name simplifies the job of the Web services runtime, which includes marshaling/unmarshaling and passing of parameters to the correct service implementation.
The WSDL document from Example 5.1 is for a document-style Web service. The soap:binding style="document" identifies the service as having document style, and data types used in the messages are defined using XML schema constructs either within the WSDL document or as a separate schema imported by the WSDL definition. Defining the data types in an imported schema is known as literal encoding that is specified by the use attribute of the body element, such as soap:body use="literal".
SOAP encoding is another schema defining a generalized set of data types and a mechanism which maps the data to implementation that is used by Web service runtimes. The schema emerged as part of the WSDL standard in the early days of Web services, before XML schema usage became commonplace. SOAP encoding has become unnecessary with the advent of XML schemas.
Theoretically, there are four possible combinations of style and encoding, as seen in Table 5.1. RPC-style Web services were originally used with SOAP encoding before literal encoding. While document-style Web services are only used with literal encoding, document-style SOAP encoding is uncommon. The document/literal style is supported by most vendors.
Extensibility of Web Services Standards (WS-*)
Standardization enables interoperability between vendors and technology platforms. For Web services, the standards that support communication between services are pivotal in supporting interoperability between services implemented using a variety of heterogeneous platforms and technologies. However, the SOAP, WSDL, and UDDI standards fail to address non-functional or QoS requirements common in implementing any SOA, such as transactionality, reliable message delivery, and security. The Web services standards manage these non-functional QoS requirements by adopting the approach of extensibility. Building on the core Web services standards are a number of WS-* standards that each define a way of extending Web services to provide additional capabilities. WS-* standards also define a contract between service consumers and services that often involves passing information between services in a SOAP header.
The WS-* standards stack addresses a number of areas including composition management, quality of service, service description, messaging, and transport protocol. Interoperable message exchange is provided by messaging standards, such as SOAP and XML, which rely on the use of existing transport protocols for communication between services.
WS-* standards are also composable, so that one standard can utilize another to provide required capabilities. For example, WS-Addressing provides a standard way of specifying a service’s address in a SOAP message. WS-Notification and WS-Eventing standards that provide publish/subscribe capabilities for Web services use WS-Addressing to specify a service’s address to which publications should be sent.
The following are common examples of WS-* standards that build upon the core SOAP and WSDL standards to provide various QoS features.
WS-Addressing
A common requirement of Web services is the ability to pass a reference to a Web service endpoint as part of a SOAP message. For example, a service consumer must provide the return address to a service when requiring an asynchronous response to an invocation via a callback. Another example is a publish/subscribe messaging paradigm used in conjunction with Web services standards. In this case, subscribers need a way of telling the broker where to send publications.
The WS-Addressing standard provides a way of passing reference to endpoints by defining an endpoint address syntax, standard SOAP headers, and Universal Unique Identifiers (UUIDs) without any dependency on what application-level protocol or API is used, such as HTTP over SMTP (HTTP/SMTP) or the JMS. A syntax specifies the address of a Web service in sufficient detail, such as the URI, service name, port type, and other required parameters. With the endpoint address syntax, a number of SOAP headers can specify where the replies and faults are sent. A standard header specifies a UUID that can be used within a response or fault to identify the related request.
The Account Enquiry service examples in this chapter are based on calling the service using a synchronous request/response message exchange pattern (MEP). The SOAP request is made over HTTP, and the service consumer waits for the SOAP response in an HTTP response. In many cases, using this synchronous request/response MEP is not possible because the service cannot produce the response quickly enough. Using an asynchronous request/response MEP can resolve delays in response caused by the need to take complex processing, manual steps, or temporary unavailability of one of the systems. The service can accept the request and return an acknowledgement before returning the response at some later point via a callback.
If an asynchronous response pattern is used to expose the Account Enquiry service, a sample WS-Addressing header generated by a service consumer is created, as shown in Example 5.5.
<SOAP:Envelope xmlns:SOAP="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/ addressing">
<SOAP:Header>
<wsa:MessageID>uuid:9ef7732-0039-be1f-492a-0db152f8ee3f
</wsa:MessageID>
<wsa:ReplyTo>
<wsa:Address>http://personalbanking.services.example.com/
PersonalBankingService</wsa:Address>
</wsa:ReplyTo>
<wsa:To>http://personalbanking.services.example.com/
Accoun tInformationService</wsa:To>
<wsa:Action>http://com.example.services.personalbanking/
Ac countDetails/AccountEnquiry/input1</wsa:Action>
</SOAP:Header>
</SOAP:Envelope>
Example 5.5 A service consumer generates a WS-Addressing header after the Account Enquiry service is exposed.
The MessageID identifies the request and is copied into the associated response by the service. The service consumer uses the response address to identify the corresponding request and specify the endpoints indicating the address the response should be sent to by the service.
In order to use WS-Addressing, an endpoint must be exposed that can be referenced by a URI. The service to which the request is addressed, and the operation being invoked, are identified by the wsa:To and wsa:Action elements. The action can either be explicitly defined within the service’s WSDL definition by including wsa:Action elements or by using a default syntax involving a concatenation of the service namespace, port type, and message name.
SOAP with Attachments (SwA)
Web services often require SOAP messages to carry some binary data, such as an image of a scanned document. Directly embedding binary data in a SOAP message is not possible because XML language is character data. Encoding the binary as character data, such as Base64 encoding, bypasses this limitation. However, Base64 encoding inflates the size by approximately one third, which results in a performance penalty and increased CPU processing due to parsing expenses.
The first set of standards to handle attachments was SOAP with Attachments (SwA). However, SwA specifications were not universally adopted. Microsoft pursued alternative approaches, first publishing the Direct Internet Message Encapsulation (DIME) specification and then the Message Transmission Optimization Mechanism. The MTOM is based on SOAP 1.2 and described in a W3C specification.
SwA, DIME, and the MTOM use multipart MIME messages in which the SOAP message is one of the parts and includes an XML reference to an attachment contained within another part. As MIME allows binary data to be directly included as part of a multipart message, the performance issues associated with Base64 encoding of binary data are avoided. The WS-I Attachments Profile is based on SwA although the support offered by the Java Web Services platform covers both the JAX-WS and AXIS2, which support SwA and the MTOM. Therefore, the interoperable implementation of SOAP attachments can be best achieved by using the MTOM.
WS-ReliableMessaging
The core Web services standards are extensible to handle multiple transport mechanisms. In practice, HTTP is the most common choice in contemporary Web service implementations. While HTTP has advantages in terms of broad support and interoperability, it is inherently unreliable with no guarantee of message delivery. The HTTP protocol requires a synchronous response to be returned to the sender, and the receipt of a response provides confirmation that the request was received by the endpoint. However, the absence of a response leaves the sender in doubt about the status of the interaction. It is possible that either the request had failed to reach the destination, or that it was received but the response had failed to reach the sender.
Reliable messaging is generally inapplicable where the operation invoked is read-only. However, when driving an update to some entity or initiating a business process, the outcome of an invocation must not be left in doubt.
Note
Where SOAP over HTTP (SOAP/HTTP) is used as transport for a one-way Web service, a response is still returned to the sender in the form of an HTTP response, which does not contain a SOAP message.
Achieving reliable messaging with HTTP can be resolved through careful design of idempotent service interfaces. If a response is not received after an idempotent service is invoked, the message can be safely resent multiple times without deleterious effects until a response is received.
A transport mechanism can also offer reliable messaging, such as the many messaging engines that offer a JMS interface. However, the JMS is merely an API that can hide proprietary messaging protocols without ensuring interoperability between different messaging providers. While this can be acceptable in a homogeneous environment, the JMS does not provide reliable message exchange in a heterogeneous SOA where services are implemented on a variety of platforms using different messaging transports.
As the basis for the WS-I Reliable Secure Profile, WS-ReliableMessaging implements an additional layer in the Web services stack, which provides the guarantee of reliable message delivery when an unreliable transport mechanism is used. A number of QoS options for assured delivery and elimination of duplicates are offered through WS-ReliableMessaging, as follows:
• AtLeastOnce delivery
• AtMostOnce delivery
• ExactlyOnce delivery
• InOrder delivery
The first three modes of delivery are self-explanatory, and it can be further noted that InOrder delivery allows groups of messages to be delivered in strict sequence. In each case, quality of service is achieved using a reliable messaging layer that sits between the SOAP stack and the service implementation. The two ends of this reliable messaging layer are called the RM source (on the sender side) and RM destination (at the receiving end). Quality of service is achieved using unique identifiers carried in a SOAP header, with communication between the RM source and destination acknowledging receipt of messages and coordinating redelivery if required. The source and destination must be stateful to know the current state of each RM interaction.
Additional QoS considerations, such as the ability to resume an interaction following the failure or restart of a service, depend on implementation details, such as how state is managed by the RM layer. WS-ReliableMessaging focuses solely on the protocol and wire format and does not cover these considerations, which are left as implementation options.
WS-Transaction
Service composability allows existing services to be reused for new purposes and composite applications to be built by assembling services in new ways through aggregation and orchestration. However, services built in this way must ensure systems and entities updated by the services are always left in a known, consistent state, regardless of any errors that might occur during the execution of one or more services included in the composition. Maintaining transactionality is common in distributed systems design, and familiar in the domain of relational databases and messaging systems. Standards for distributed transactions, such as the Open Group’s XA protocol, provide a way for transaction managers to interact with multiple resource managers and guarantee the ACID properties of distributed transactions.
The three OASIS standards, which collectively make up WS-Transaction, address the issue of transactionality with WS-Coordination, WS-AtomicTransaction, and WS-BusinessActivity. Within the context of these specifications, a coordination is either a short-lived series of service invocations or a long-lived sequence of business activities. In each case, coordination must be performed as an atomic set.
WS-Coordination defines a standard way for services to participate in a composition by exposing a coordination service or coordinator. The coordination service must implement activation and registration methods defined within the WS-Coordination specification. Activation allows services to participate in a new coordination by creating a new coordination context, while registration allows services to participate in an existing coordination. In addition to the interactions between services, coordinators interact using a protocol specific to the coordination type not defined within the WS-Coordination specification.
WS-AtomicTransaction defines a coordination protocol for short-lived transactions and provides a distributed two-phase commit protocol conceptually similar to a Web service-enabled version of XA.
For long-lived coordination, WS-BusinessActivity is useful when the two-phase commit approach of locking resources for coordination is unreasonable by defining a relatively complex set of states with well-defined transitions. The basic approach to transaction management is compensation. Services must be able to compensate or undo operations if required to restore a consistent state following a failure in another service involved in a coordination.
WS-Security
Often, the advantages of implementing Web-based services can render them particularly susceptible to attack, such as the firewall-friendly HTTP protocol. A common requirement is to restrict access to authenticated callers, which is addressed by the OASIS WS-Security standard.
The base WS-Security specification supports authentication by defining a message model for the transmission of security tokens within SOAP messages, and allows the use of different security models and systems by supporting the use of different types of security tokens. The tokens can be either unsigned or signed, such as a token containing a user id or password pair used for basic authentication or a digital certificate signed by a trusted certificate authority. Both scenarios are supported by the Web Services Security UserName Token Profile 1.0 and Web Services Security X-509 Certificate Token Profile 1.0, which form part of the WS-Security specification set.
By allowing SOAP messages to be signed with digital signatures and encrypted to ensure confidentiality when exchanged between services, WS-Security offers a means of ensuring message integrity and privacy. WS-Security supports different mechanisms for exchanging security tokens, which can be unsigned or signed by an authority with which the service has a trust association. Achieving interoperability between heterogeneous Web service implementations requires the use of security standards supported by all implementations.
X.509 certificates and Kerberos tickets are examples of commonly used signed tokens. The WS-Security specification allows for the use of binary security tokens, such as X.509 certificates, by defining a basic mechanism for inlining Base64-encoded tokens within the SOAP security header, and by extension the use of additional encoding schemes.
The WS-I Security Basic Profile establishes requirements to achieve interoperability with WS-Security-enabled services similar to what the WS-I Basic profile achieves for general interoperability. As with the other WS-* standards that provide enhanced QoS for Web services, WS-Security allows the decisions to be implemented through configuration, keeping the service implementation free of the details of how the services are secured.
WS-Policy
WS-Policy is a W3C recommendation that allows the behavior, requirements, and characteristics of Web services to be specified as policies using an extensible syntax. A policy is defined as a set of policy alternatives, each consisting of a group of policy assertions that describe some requirement or characteristic of a service. Policies can cover a broad variety of concerns. Some policies describe technical aspects of the service’s interaction, such as exchange of security and transaction context, while others are conceptual, such as description of the service’s ownership or usage policy.
WS-Policy provides a means for WSDL-described Web services to express their requirements and characteristics in a standardized manner to potential service consumers. For example, the WSDL document describing a service is retrieved at development time and examined by a designer or developer who is considering using the service. This potential user can consider information included in WS-Policy expressions when evaluating the service’s suitability, and is able to ensure that any stated requirements of the service are met when developing a service consumer. WS-Policy also supports negotiation between service consumers and services at runtime, such as when the service consumer and service both declare the security mechanisms they support and agree on a mutually acceptable option before invocation.
However, WS-Policy is not useful on its own and is often connected with a number of other specifications, such as the WS-Coordination and WS-Security specifications. Policies defined using WS-Policy assertions can be grouped as policy sets, which allow combinations of behaviors to be specified with a single definition. Grouped policy sets are useful when particular combinations of policies are frequently used.
Web Services Distributed Management
The Web Services Distributed Management (WSDM) specification from OASIS provides a standard way of managing resources within a Web services landscape. The Management Using Web Services (MUWS) WSDM specification describes the use of Web services interfaces to manage resources, which allows resources to be discovered, controlled, and queried for operational status. The Management of Web Services (MOWS) specification builds on MUWS to describe the specific scenario where the resources being managed are themselves exposed as Web services. The two specifications provide a standard means of managing services, limiting their scope to services implemented based on Web services standards.
Common Web Services Middleware
SOA infrastructure products can provide a range of extensions to Web services-based architectures, as explored in this section. This type of middleware provides various value-added features on top of the core SOAP and WS-* stack implementations, such as mediation, service composition, orchestration, management, and monitoring.
Enterprise Service Bus (ESB)
ESBs provide connectivity between components, mapping between incompatible interfaces, and perform processing on messages en route through the middleware infrastructure. However, the ESB emphasizes support for WSDL, SOAP, and the mature WS-* standards not included in the integration broker or MOM technologies.
ESB products differ in implementation and terminology. The service bus is a logical entity, which can span multiple geographical locations. In order to provide connectivity to a service, the ESB must first be configured to connect to the service via some kind of off-ramp or outbound port. Once the ESB has been configured to connect to a service, the service can be made accessible to any other service with a connection to the bus by exposing an interface that acts as the corresponding on-ramp or inbound port.
For example, to expose a Web service via the ESB, the ESB must act as a service consumer. To make the Web service accessible to other service consumers, the ESB then exposes an interface and provides a WSDL description for consumption by other services.
In the simplest case, for example, the inbound and outbound interfaces match. The abstract WSDL definitions are the same, and the concrete WSDLs only differ by a different endpoint address being specified. The ESB must receive a message as a proxy service via the inbound interface and call the target service via the outbound interface. No mapping between interfaces is required.
Connecting services via an ESB, instead of connecting them directly, means that logic can be encapsulated within the bus and processing can be performed on messages en route between services. Mediations can be used for many different purposes, and some common use-case scenarios include:
• transforming the message in some way, such as mapping between different XML schemas
• performing protocol translation, such as SOAP/HTTP to SOAP over JMS (SOAP/JMS)
• dynamically routing the message to one of a number of endpoints, such as those based on the availability of target service instances
• throttling to restrict the load on target services, and prioritizing requests
• logging, auditing, and management of the service runtime environment
• providing security capabilities for incoming and outgoing messages, including authentication, authorization, encryption, and digital signing
Chapter 12 is dedicated to exploring the ESB as a means of adding middleware for Java-based service-oriented technology architectures.
Orchestration
Implementing a business process within an SOA involves modeling the process and then mapping the tasks within the process to services. For each task, the service inventory is examined to identify existing candidate services, and a new service is defined and implemented where no suitable service exists. As the service inventory grows, with careful design for reuse, an increasing number of business processes can be realized by orchestrating existing services from the service inventory.
Constructing coarse-grained composite services is possible by aggregating atomic services with finer-grained composite services. Business processes often consist of specific steps or tasks executed by an automated process or human interaction in a well-defined, predictable fashion.
Implementing a business process using the Java EE stack can be achieved by writing Java code to control the execution of steps. However, the process model is then encapsulated in complicated Java code. Realizing the model requires Java development skills beyond a typical business analyst’s capabilities, and requires interpretation by the Java developer implementing the process. Instead, business processes can be specified in a declarative fashion to avoid Java development. The model can be interpreted by an orchestration engine and used to control the execution of the process. WS-BPEL provides a means of specifying the orchestration of WSDL-described Web services in long- and short-running processes. Executable models are fundamental to the WS-BPEL standard.
The Java EE specification does not include support for WS-BPEL or any comparable standard. However, the orchestration of services is a fundamental aspect of SOA, and WS-BPEL support is included as an option in most Java-based SOA infrastructure implementations and in the Microsoft platform.
Business processes commonly include a mixture of automated (machine) and manual (human) steps. In each case, the task can be modeled as a step that accepts one or more inputs and returns zero or more outputs. When implemented as an automated task, the process calls a service with a matching interface. In the case of a human task, the process pauses at this point and places an item on a work list, waiting for an appropriate person to claim and complete the task. Manual steps are completed via a user-interface, which displays the task’s input parameters and waits for users to provide the required output parameters in order to complete the task and continue the process.
Processes can be constructed with a mixture of manual and automated tasks and even require the ability to change implementation between the two styles as part of process change and optimization. Most Java vendors provide extensions to WS-BPEL, which provide support for manual tasks within processes. Manual tasks in some vendor implementations are described with a WSDL interface in the same way as Web services included within a process.
Beyond a lack of support for manual tasks, WS-BPEL is unable to specify whether processes and subprocesses are short-lived or long-lived. In the case where processes are long-lived and steps within the process cannot be completed within seconds, having the process container hold the process state in-memory is unreasonable. The process container must instead persist the state of a process instance at the end of each step, such that it can be retrieved when some input is received to progress the process instance.
It is possible to treat all process instances as long-lived. However, holding process state in-memory can significantly impede performance. This limitation is again resolved with vendor-specific extensions to WS-BPEL, which allow process state in the process container to be specified by the designer as in-memory or persistent. Despite the challenges, WS-BPEL is the dominant standard for the orchestration of services in an SOA. Unlike other standards which allow the specification of processes in an abstract, high-level fashion, WS-BPEL processes include low-level implementation details, such as WSDL interface specifications, so that processes are executable.
WS-BPEL provides the following capabilities:
• composition of services into long and short-running processes, which can themselves be exposed as services
• specification of process logic in a model, which can be viewed graphically instead of as Java code
• management of process state, which includes the ability to record and monitor the state of process instances through deployment into a process engine
WS-BPEL plays an integral role in modern BPM, optimization, and reengineering, which involves a modeling approach to automating business processes using an orchestration engine. Through a combination of process execution simulation and monitoring, process logic and flows can be continuously adjusted to optimize process efficiency.
Management and Monitoring
Monitoring services in an SOA to ensure that they satisfy response time, availability, and other non-functional requirements can be more difficult than monitoring systems and components in a traditional distributed architecture. Service monitoring is relatively straightforward in the case of atomic services. However, other types of services, such as composite services and legacy wrapper services, have operational dependencies on other services, components, or systems.
In the case of a monolithic system running on a mainframe, monitoring the availability of the system is a question of monitoring the availability of the operating system and processes on which the system depends. In the case of a service in an SOA, the service might depend on other functionality implemented with a number of technologies and deployed across multiple servers. In operation, knowing which services are affected when a server crashes, or which component is responsible for the degraded response times achieved by a particular service, is necessary. Taking action when a fault has occurred can be required, perhaps by rerouting to another instance of the service in a different data center or by rejecting low-priority requests.
Registries and Repositories
During the early years, adoption of service registries proved more popular as a tool for use at design-time and development-time. One common example was for a registry to be shared between development teams, and for developers to search the directory’s service inventory for services that might be reused as part of the development at hand. The WSDL definitions for any suitable services can then be imported and used to generate client or proxy classes.
The role of the service registry within an SOA has since expanded. If considering all of the aspects of the service lifecycle, information about a service is required for many different purposes, such as:
• during design-time to search for existing services suitable for reuse
• during development to retrieve service definitions (WSDLs)
• before deployment by providing input to reviews to satisfy governance requirements
• following deployment to support configuration of service monitoring and management infrastructure
• at runtime to support endpoint selection by an ESB or service consumer
• to track dependencies between services, for example to support impact analysis
Accessing information in any of these scenarios requires access to service metadata that can be stored on a single registry rather than distributed across multiple stores, which then require synchronization.
A number of vendors have adopted the expanded role of a registry, and responded by developing registry/repository products to satisfy a wide variety of use cases. Many of these products provide some level of UDDI support, with many proprietary and non-standards-based features. To support SOA governance, most of these vendor registries include a well-defined model of the service lifecycle. Workflow features support controlled transition between the states of the lifecycle by corresponding governance actions, such as moving a service from “ready for review” to “ready for release” by completing a review task.
Service Construction and Assembly
SOA aims to deliver services that can be utilized in the construction of composite applications. One example of composition is the orchestration of services within a business process. The tools and specifications of BPM allow processes to be modeled as a series of tasks, with each of the tasks bound to an underlying service implementation. Within early WS-BPEL implementations, the service binding is achieved with static configuration and the task is bound to a specified WSDL operation.
Vendors and analysts have gradually shifted their focus towards more dynamic styles of composition which support the agility demanded by rapidly changing business environments.
Note
More information about any of the aforementioned Web services industry standards and specifications can be found at www.servicetechspecs.com.
5.2 REST Services
In this section, we briefly explore REST service design by highlighting some of the key technology and programming considerations.
Note
For an in-depth exploration of REST service design and the convergence of REST constraints and service-orientation principles, see the series title SOA with REST: Principles, Patterns & Constraints for Building Enterprise Solutions with REST. If you are building services for a service-oriented architecture using REST, it is highly recommended that you read this book. Note also that the REST design constraints referenced in this chapter are covered in this book and are also described at www.whatisrest.com.
A REST service is required to expose resources that include:
• one or more representations, either expected or provided
• an address to uniquely locate the resource
• a set of HTTP methods exposed at the interface level
• metadata carried in headers for requirements, such as security tokens or caching information
The service definition or service contract details the specific attributes for the service. For example, let’s look at a REST service that retrieves a customer list and the details of an individual customer. In order to define the Customer Listing service using REST, we need to address the following questions:
• What is the root resource and address for accessing this service?
• Once the service consumer accesses this address, what attributes of a customer will be shown as part of the customer listing?
• How will service consumers retrieve details of an individual customer from a list of customers?
• What is the representation of the customer details?
• Will there be links to related resources, such as an account?
• Can the service consumer update or create new customers?
• What security credentials and other attributes are required by the service in order to provide the customer information to the service consumer?
HTTP Response Codes
In a REST-based service interaction, standard HTTP methods (GET, PUT, POST, DELETE, HEAD, and OPTIONS) are used together with HTTP response codes to establish a communications framework based on a uniform contract that can invoke service capabilities and communicate success, failure, and error conditions.
A typical response code is captured in the first line of the HTTP response, with a number and corresponding self-explanatory description string. There can be additional details in the response body sent by the service. Most response codes have accompanying metadata in pre-defined HTTP headers essential for service consumers to make further decisions. For the discussion of this chapter and general industry use, service consumers often base their decisions on the response code along with the HTTP headers.
The key response codes based on the HTTP standard are as follows:
• 200 (“OK”) – The request was successful.
• 201 (“Created”) – The resource has been successfully created.
• 206 (“Partial Content”) – The server has fulfilled a partial GET request for the resource.
• 301 (“Moved Permanently”) – The requested resource has moved to a different location, and should include the updated location of the resource in the Location header field.
• 302 (“Found”) – The client must perform a temporary redirection (the Location header is used to point to the URI of the resource).
• 303 (“See Other”) – The response to the request can be found using another URI with a GET method (the 303 response must not be cached, but the response to the redirected request may be cacheable).
• 400 (“Bad Request”) – A service consumer-side error occurred in the invocation of the service request.
• 401 (“Unauthorized”) – The service consumer lacks the necessary authentication credential to make the request.
• 403 (“Forbidden”) – The service consumer has supplied all relevant information (well-formed request and any authentication credentials), but the server refuses to fulfill the request.
• 404 (“Not Found”) – The requested resource is not found.
• 409 (“Conflict”) – The request cannot be completed due to a conflict with the current state of the resource.
• 415 (“Unsupported Media Type”) – A representation of the request that is not supported by the service is sent.
• 500 (“Internal Server Error”) – The server encountered an unexpected condition and was unable to fulfill the request.
• 501 (“Not Implemented”) – The server does not support the functionality required to fulfill the request.
Resources and Addresses
A top-level address in the form of a URL is needed to expose the service. The concrete URL is of lesser importance than the context path to the service. With that in mind, a context for listing customers must be exposed. At the top level, the list of customers can be serviced by a choice of a resource, the collection of customers, and an associated URL, such as http://server/services/customers.
However, the individual details of a customer cannot be retrieved without navigation to a child resource of the collection of customers, an individual customer entity. In REST-based service design, containment relationships are represented by path parameters with a URL of the form, /parent/{child-identifier}. An individual customer resource can be retrieved at the URL http://server/services/customers/1234.
Assuming the resource representation is in XML (MIME type is application/xml), the service requests and responses are illustrated in Example 5.6.
Service Request
GET services/customers HTTP/1.1
Host: server
Service Response
HTTP/1.1 200 OK
Content-Type: application/xml;charset=UTF-8
<customers xmlns:atom="http://www.w3.org/2005/Atom">
<atom:link rel="self" ref="http://server/services/customers/">
<customer>
<id>1234</id>
<atom:linkrel="self" href="http://server/services/customers/12 34"/>
<name>Jack Daniel</name>
</customer>
<customer>
...
</customer>
</customers>
The Customer Details service returns the request and response in Example 5.7.
Service Request
GET services/customers/1234 HTTP/1.1
Host: server
Service Response
HTTP/1.1 200 OK
Content-Type: application/xml;charset=UTF-8
<customer xmlns:atom="http://www.w3.org/2005/Atom">
<id>1234</id>
<atom:link rel="self"href=http://server/services/customers/123 4/>
<first-name>Jack</first-name>
<last-name>Daniels</last-name>
<e-mail>[email protected]</e-mail>
<phone>999-999-9999</phone>
...
</customer>
Each of the resources, including the collection, has a link identifier element pointing to a href address attribute where this resource can be located. All of these elements and attributes are defined in the Atom Syndication Format specification, which is a standard method of describing Web feeds.
Retrieving a collection of resources, the details of an individual member resource in the collection, representation format, and resource content’s carrying levels of details occur with a containment hierarchy via the customer id path parameter. Navigating to a related resource enforces the hypermedia constraint.
Example 5.8 shows how to retrieve account information for a customer.
<customer xmlns:atom="http://www.w3.org/2005/Atom">
<id>1234</id>
<atom:link rel="self"href=http://server/services/
customers/1234/>
...
<accounts>
<account>
<id>c1234-001</id>
<atom:link rel="account"
href=http://server/services/accounts/c1234-001/>
<typecode>CHK</typecode>
<currency>USD</currency>
<balance>5000</balance>
...
</account>
<account>
...
</account>
</accounts>
</customer>
The <link> element guides the service consumer of the root resource, such as the customer, to a related resource, such as an account, through an embedded hyperlink, such as http://server/services/accounts/c1234-001. The service consumer requires no extra information, as the application state is transitioned from representing a customer’s information to related account information via hypermedia.
The semantics of the link relation are described by a link relation extension, such as the attribute value of rel, indicating that this relation describes an associated account. Other than the semantics shared beforehand, the service consumer does not need to know all the resources and their addresses, as these can be discovered through links embedded in resources.
Link relation is the basis of the hypermedia constraint. In a well-designed REST-based system, link relation can be a powerful technique that highlights the importance of exposing a well-known URL as a root resource to service consumers and letting them discover the related resources through embedded links. Decreased coupling accompanies this approach, as the service consumer needs to know less about the service.
Making the URLs informative and neutral is a design decision. Depending on the nature of the service consumer, keeping the URLs understandable to humans is always useful. Traditional Web URLs end in HTML or WML. Although it is good practice to denote the type or representation of the resource being accessed on the Web, doing so may not make sense in a REST-based service design. Therefore, if an XML and HTML representation of the same resource must be provided, the URI for a customer listing is morphed to two specific URLs with extensions, as shown in Example 5.9.
http://server/services/customers/xml
http://server/services/customers/html
Although URLs convey the meaning, there are better ways of representing and requesting the different representations of the resources. For machine-processable REST services, URIs should be kept neutral, informative, and readable.
HTTP Methods
Now with the service URLs defined, the HTTP methods needed to realize the requirement of viewing a customer listing can be explored. Let’s first review the various HTTP methods and their intended use within a REST service. Each of these methods has valid responses based on various conditions.
This section will only highlight the most prominent HTTP methods as follows:
• GET is solely used to view and read resources. The service consumer can call the GET method any number of times on the resource using the URL and receive the same result in return. In other words, GET is side effect-free and idempotent. The response, such as 200 OK, to a GET request from a service consumer is well defined by the HTTP specification.
• DELETE is used to delete the resource, can be called once, and is idempotent but not side effect-free. Nothing happens when the caller invokes the DELETE method on an already deleted resource.
• HEAD is a lighter version of GET, which is used to check on the availability of a resource. The HTTP GET method returns only the response headers and not the actual content of the resource. The HEAD method can be invoked to see if a resource is found at a given URL. If the response is 200 OK, then a GET can be issued to access the resource. HEAD, like GET, is side effect-free and idempotent.
• PUT is traditionally used to update resources. Using this method, the service consumer sends in the entity representation to a known endpoint to update the resource. Repeating PUT simply updates the same resource with the same entity details, as it is idempotent but not side effect-free. In some rare situations, PUT can also be used to create resources when the client knows the URI of the resource to be created.
• POST is a versatile method that is causing some confusion in REST and Web discourse. Most developers are familiar with POST from HTML form submissions and SOAP/HTTP communications. In reality, this method can be used to create resources or perform operations that cannot be easily handled via the other verbs. The usage is based on the context of service and the desired functionality. POST is neither side effect-free nor idempotent.
• OPTIONS provide a mechanism for the caller or service consumer to perform simple access control checks.
The properties of idempotency and safety, as implied by side effect-free, are key design considerations for REST services determining reliability and other qualities of service, such as efficient performance. Two other auxiliary methods, known as TRACE and CONNECT, can be ignored in this discussion of REST services for simplicity.
The HTTP method can be used to identify what methods the service must support to realize the use case of listing customers. Listing the details of a particular customer using services/customers/{id} is a view operation exposing GET, HEAD, and OPTIONS methods. Sending a GET request to the URL will return the customer details, sending a HEAD request will return a valid response consisting of only the headers without the actual response body, and sending an OPTIONS request will show that only GET and HEAD are allowed for all users.
Resource Representations
After defining resource methods, the representation of the request and response to the service can be reviewed. Using XML schemas is a standard approach for representing a resource. The REST service requests and responds to XML payloads that conform to a prescribed XML schema. However, for Web applications implemented in JavaScript via AJAX (JavaScript/AJAX), representing the resource in JavaScript Object Notation (JSON) can be considered an alternative. JSON describes the data in a name-value format.
{
customer:
{
name:"John Smith",
e-mail:"[email protected]",
phones: [
{"home":"444-444-4444"},
{"work":"555-555-5555"}
]
}
}
In Example 5.10, the customer is a container of various name-value pairs of attributes including an array of phone numbers. The content type is application/json, similar to application/xml or text/xml for the XML representation. When using HTTP functionality with a REST framework, the JSON format is also commonly supported. A Web application consuming this service from a browser can process the response with little overhead, as these are simply messages that happen to be another JavaScript object. JSON can yield a multitude of useful representations, such as an XHTML representation, for a more conventional Web-based service consumer.
An XML representation can be used with standardized Atom <link> elements to identify self-describing resources via the embedded URIs that facilitate navigability from one resource to another. JSON has no formal concept of hyperlinks, but a convention can be followed to embed a URI as a text value of a custom property. The service consumer must know about this custom element for resource navigation beforehand, which introduces a degree of coupling that is not applicable for a standards-based, Atom-aware client.
The information requested can be encoded in a URL or URI. A design decision must be made as to when to use content representation as part of the request/response, and when to keep the information as part of the URI. In general, the HTTP methods and flexibility required by the service consumer will determine whether the information will be encoded in the URI or in the body of the request.
Recall the steps taken to request a specific customer by extending the initial service URI to have cust_id as a parameter. These were read-only resources (using the GET method) with no use in having a content body. Alternatively, SOAP-based services can use the request body to send the information with the POST method. The customer ID can be encoded in simple XML and used in the request to indicate which customer is requested.
The ACCEPT Header
Some standard HTTP headers required by the HTTP specifications can be extended to provide custom HTTP headers. While maintaining standards for scalability and interoperability is preferable, specific cases can warrant extending and creating custom HTTP headers between services and service consumers to address non-functional requirements. This section introduces the Accept header, which connects the REST service design concepts with the service-orientation design principles.
The Accept header is used by the service consumer in the request to indicate the desired content expected in the response from the service. The value used in the Accept header is any one of the content type values from the HTTP specification. The Accept header can be set to the values seen in Example 5.11 if the service consumer requires a JSON or XML representation of the content, maintaining the simplicity of the URIs while locating metadata into the HTTP headers.
Accept: application/xml
Accept: application/json
Example 5.11 can be applied to the Customer resource listing from Example 5.8. The first request is a GET request to the /customers URI, with the Accept header set to XML. The response the service consumer receives is a list of customers. The following request is a GET request for the customer with id c1234 at the URI /customers/c234, with the Accept header set to XML. The information returned is an XML representation of the customer.
When the Customer resource is requested via a GET invocation with an Accept header indicating a JSON representation of the resource, the service must return a JSON representation of the customer information. When an attempt is made to DELETE the customer concerned, the server responds with response code 405, indicating the operation is not allowed in this context.
Note
For access to industry standards and specifications relevant to REST, visit www.servicetechspecs.com.