Home > Articles

The SOAP Protocol

This chapter is from the book

The Transport Binding Framework

The SOAP processing model talks about what a node should do when it processes a SOAP message. As we've discussed, messages are described abstractly in terms of the XML infoset. Now it's time to look more closely at how those infosets are moved from place to place.

A SOAP protocol binding is a set of rules that describes a method of getting a SOAP infoset from one node to another. For instance, you already know that HTTP is a common way to transport SOAP messages. The purpose of the SOAP HTTP binding (which you'll find in part 2 of the spec) is to describe how to take a SOAP infoset at one node and serialize it across an HTTP connection to another node.

Many bindings, including the standard HTTP one, specify that the XML 1.0 serialization for the infoset should be used—that means if you look at the messages on the wire, you'll see angle brackets as in any regular XML document. But the binding's job is really to move the infoset from node to node, and the way the infoset is represented on the wire is up to the binding author. This means bindings have the freedom to specify custom serializations; they might do this to increase efficiency with compression or a binary protocol, or to add security via encryption, among other reasons.

Since bindings determine the concrete structure of the bits on the wire and how they're processed into SOAP messages, it's critical that communicating parties agree on what binding to use—that agreement is just as important as the agreement of what data to send. This is why bindings, like SOAP modules, are named with URIs. The standard SOAP 1.2 HTTP binding, for instance, is identified by the URI http://www.w3.org/2003/05/soap/bindings/HTTP/. Note that there can be many different SOAP bindings for a given underlying protocol—agreeing on a binding means not only agreeing to use HTTP to send SOAP messages, but also to follow all the rules of the given binding specification when doing so.

Bindings can be simple or complex, and they can provide a variety of different levels of functionality. A raw UDP binding, for instance, might not provide any guarantee that the messages sent arrive at the other side. On the other hand, a binding to a reliable message queuing system such as the Java Message Service (JMS) might provide guaranteed (eventual) arrival, even in the face of crashes or network failures. We can also imagine bindings to underlying protocols that provide security, such as HTTPS, or with the ability to broadcast messages to a variety of recipients at once, like multicast IP.

Even when the underlying protocol doesn't provide desired functionality directly, it's still possible to write a binding that does fancy things. For instance, you could design a custom HTTP binding specifying that, for security reasons, the XML forming each message should be encrypted before being sent (and decrypted on the receiving side). Such custom bindings are possible, but it's often a better idea to use the extensibility built into the envelope to implement this kind of functionality. Also, bindings only serve to pass messages between adjacent nodes along a SOAP message path. If you need end-to-end functionality in a situation where intermediaries are involved, it's usually better to use in-message extensibility with SOAP headers.

Features and Properties

Bindings can do a huge variety of different things for us—compare this variety to what the SOAP header mechanism can do, and you might notice that the set of possible semantics you can achieve is similar (almost anything, in fact). The designers of SOAP 1.2 noticed the similarity as well, and wanted to write a framework that might help future extension authors describe their semantics in ways that were easy to reason about, compare with each other, and refer to in machine-readable ways.

What was needed was a way to specify that a given semantic could be implemented either by a binding or by using SOAP headers. Nodes might use this information to decide whether to send particular headers—if you're running on top a secure binding, for instance, you might not need to add security headers to your messages, which can save your application effort and time. Also, since a variety of modules might be available to an engine at any given time, it would also be nice to be able to unambiguously indicate that a particular module performed a certain set of desired semantics. To achieve these goals, the first job was to have a standard way to name the semantics in question.

The SOAP authors came up with an extensibility framework that is described in section 3 of part 1 of the SOAP 1.2 spec. The framework revolves around the notion of an abstract feature g, which is essentially a semantic that has a name (a URI) and a specification explaining what it means. Features can be things like reliability, security, transactions, or anything you might imagine. A feature is typically specified by describing the behavior of each node involved in the interaction, any data that needs to be known before the feature does its thing, and any data that is transferred from node to node as a result. It's generally convenient if the specification of the feature's behavior can be found at the URI naming the feature—so if a user sees a reference to it somewhere, they can easily locate a description of what it does.

The state relevant to a feature is generally described in terms of named properties g. Properties, in the SOAP 1.2 sense, are pieces of state, named with URIs, which affect the operation of features. For instance, you might describe a "favorite color" feature that involves transferring a hexadecimal color value from one node to another. You would pick a URI for the feature, describe the rules of operation, and name the color property with another URI. Because a feature definition is abstract, you don't say anything about how this color would move across the wire.

Features are expressed (turned into reality via some mechanism) by bindings and modules. We've already described both of these—recall that a binding is a means for performing functions below the SOAP processing model, and a module is a means for performing functions using the SOAP processing model, via headers.

Here's a simple example of how a feature might be expressed by a binding in one case and a module in another. Imagine a "secure channel" feature. The specification for this feature indicates that it has the URI http://skatestown.com/secureChannel, and the abstract feature describes a message traveling from node to node in an unsnoopable fashion (to some reasonable level of security). We might then imagine a SOAP binding to the HTTPS protocol, which would specify that it implements the http://skatestown.com/secureChannel feature. Since HTTPS meets the security requirements of the abstract feature, the feature would be satisfied by the binding with no extra work, and the binding specification would indicate that it natively supports this feature. We could also imagine a SOAP module (something like WS-Security, which we discuss in Chapter 9, "Securing Web Services") that provides encryption and signing of a SOAP message across any binding. The module specification would also state that it implements the secureChannel feature. With this information in hand, it would be possible, in a situation that required a secure channel, to decide to engage our SOAP module in some situations (when using the HTTP binding, for instance) and to not bother in other situations where the HTTPS binding is in use.

Another example of making features concrete could be the color feature discussed earlier. The feature spec describes moving a color value from the sender to the receiver in the abstract. A custom binding over email might define a special SMTP header to carry this color information outside the SOAP envelope. Writing a SOAP module to satisfy the feature would involve defining a SOAP header that carried the value in the envelope.

Message Exchange Patterns

One common type of feature is a Message Exchange Pattern (MEP) g. An MEP specifies how many messages move around in a given interaction, where they originate, and where they end up. Each binding can (and must) support one or more message exchange patterns. The SOAP 1.2 spec defines two standard MEPs: Request-Response and SOAP Response. Without going into too much detail (you can find the full specifications for these MEPs in the SOAP 1.2 spec, part 2), we'll give you a flavor of what these MEPs are about.

The Request-Response MEP involves a requesting node and a responding node. As you might expect, it has the following semantics: First, the requesting node sends a SOAP message to the responding node. Then the responding node replies with a SOAP message that returns to the requesting node. See Figure 3.9.

Figure 3.9Figure 3.9 The Request-Response MEP

You should note a couple of important things here. First, the response message is correlated to the request message—in other words, the requesting node must be able to figure out which response goes with which request. Since the MEP is abstract, though, it doesn't specify how this correlation is achieved but leaves that up to implementations. Second, if a fault is generated at the responding node, the fault is delivered in the response message.

The SOAP Response MEP is similar to the Request-Response MEP, except for the fact that the request message is explicitly not a SOAP message. In other words, the request doesn't trigger the execution of the SOAP processing model on the receiving node. The receiving node responds to the request with a SOAP message, as in the Request-Response MEP (see Figure 3.10).

Figure 3.10Figure 3.10 The SOAP Response MEP

The primary reason for introducing this strange-seeming MEP is to support REST-style interactions with SOAP (see the sidebar "REST-Style versus Tunneled Web Services"). The SOAP Response MEP allows a request to be something as simple as an HTTP GET; and since the responding node doesn't have to implement the SOAP processing model, it can return a SOAP message in any way it deems appropriate. It might, for instance, be an HTTP server with a variety of SOAP messages in its filesystem.

As you'll see in a moment, the HTTP binding natively supports both of these MEPs. Of course, MEPs, like other abstract features, can also be implemented via SOAP modules. Here's an example of how the Request-Response MEP might be implemented using SOAP headers across a transport that only allows one-way messages:

<soapenv:Envelope
 xmlns:soapenv="http://www.w3.org/2003/05/soap/envelope">
 <soapenv:Header>
 <!--This header specifies the return address-->
 <reqresp:ReplyTo soapenv:mustUnderstand="true"
   xmlns:reqresp="http://skatestown.com/requestResponse">
  <destination>udp://me.com:6666</destination>
 </reqresp:ReplyTo>
 <!--This header specifies a correlation ID-->
 <reqresp:correlationID soapenv:mustUnderstand="true"
   xmlns:reqresp="http://skatestown.com/requestResponse">
  1234
 </reqresp:correlationID>
 </soapenv:Header>
 <soapenv:Body>
 <doSomethingCool/>
 </soapenv:Body>
</soapenv:Envelope>

This message might have been sent in a UDP datagram, which is a one-way interaction. The receiver would have to understand these headers (since they're marked mustUnderstand) in order to process the message; when it generated a reply, it would follow the rules of the ReplyTo header and send the reply via UDP to port 6666 of host me.com. The reply would contain the same correlationID sent in the request, so that the receiver on me.com would be able to match the response to the pending request. The WS-Addressing spec includes a mechanism a lot like this, which we'll cover in Chapter 8, "Web Services and Stateful Resources."

If your interaction requires the request-response MEP, you might choose to use the HTTP binding (or any binding that implements that MEP natively), or you might use a SOAP module that specifies how to implement the MEP across other bindings. The important goal of the framework is to enable abstractly defining what functionality you need—then you're free to select appropriate implementations without tying yourself to a particular way of doing things.

REST-Style versus Tunneled Web Services

REpresentational State Transfer (REST) g refers to an architectural style of building software that mirrors what HTTP is built to do: transfer representations of the state of named resources from place to place with a small set of methods (GET, POST, PUT, DELETE). The methods have various semantics associated with them—for instance, a GET is a request for a resource's representation, and by definition GETs should be safe operations. "Safe" in this context means they should have no side effects. So, you do a GET on my bank  account URL in order to obtain your current balance, you can repeat that operation many times with no ill  effects. However if the GET withdrew funds from your account, , that would clearly be a serious side effect (and therefore illegal in REST).

Another interesting thing to note about GET is that the results are often cacheable: If you do a GET on a weather report URL, the results probably won't change much if you do it again in 10 minutes. As a result, the infrastructure can cache the result, and if someone asks for the same GET again before the cache entryexpires, you can return the cached data instead of going out over the Net to fetch the same weather again. The HTTP infrastructure uses this caching style to great effect; most large ISPs or companies have shared caching proxies at the edge of the network that vastly reduce the network bandwidth outside the organization—each time anyone asks for http://cnn.com, the cache checks if a local, fresh copy exists before going out across the network.

We bring up REST because it shines light on an interesting controversy. REST advocates (sometimes known as RESTifarians) noticed that SOAP 1.1's HTTP binding mandated using the POST method. Since POSTs are not safe or cacheable in the same way GETs are, even simple SOAP requests to obtain data like stock quotes or weather reports had to use a mechanism that prevented the HTTP infrastructure from doing its job. Even though these operations might have been safe, SOAP was ignoring the HTTP semantic for safe operations and losing out on valuable caching behavior as a consequence.

This issue has since been fixed in the SOAP 1.2 HTTP binding, which supports the WebMethod feature. In other words, SOAP 1.2 is a lot more REST-friendly than SOAP 1.1 was, since it includes a specific technique for utilizing HTTP GET, including all that goes along with it in terms of caching support and operation safety. HTTP semantics are respected, and HTTP isn't always used as a tunnel for SOAP messages.

We believe that SOAP's flexible messaging and extensibility model (which supports both semantics provided by the underlying protocol and also those provided by higher-level extensions in the SOAP envelope) offer the right framework for supporting a large variety of architectural approaches. We hope this framework will allow the protocol both good uptake and longevity in the development community.

Features and Properties Redux

The features and properties mechanism in SOAP 1.2 is a powerful and flexible extensibility framework. By naming semantics, as well as the variables used to implement those semantics, we enable referencing those concepts in an unambiguous way. Doing so is useful for a number of reasons—as you'll see in Chapter 4, "Describing Web Services," naming semantics lets you express capabilities and requirements of your services in machine-readable form. This allows software to reason about whether a given service is compatible with particular requirements. In addition to the machine-readability aspect, naming features and properties allows multiple specifications to refer to the same concepts when describing functionality. This encourages good composition between extensions, and also allows future extensions to be written that implement identical (but perhaps faster, or more flexible) semantics.

Now that you understand the framework and its components, we'll go into more detail about the SOAP HTTP binding.

The HTTP Binding

You already know the HTTP binding is identified with the URI http://www.w3.org/2003/05/soap/bindings/HTTP/ and that it supports both the Request-Response and the SOAP Response MEPs. Before we examine the other interesting facets of this binding, let's discuss how those MEPs are realized.

Since HTTP is natively a request/response protocol, when using the Request-Response MEP with the HTTP binding, the request/response semantics map directly to the equivalent HTTP messages. In other words, the SOAP request message travels in the HTTP request, and the SOAP response message is in the HTTP response. This is a great example of utilizing the native capabilities of an underlying protocol to implement an abstract feature.

The SOAP Response MEP is also implemented natively by the HTTP binding and is typically used with the GET Web method to retrieve representations of Web resources expressed as SOAP messages, or to make idempotent (safe) queries. When using this MEP this way, the non-SOAP request is the HTTP GET request, and the SOAP response message (or fault) comes back, as in the Request/Response case, in the HTTP response.

The HTTP binding also specifies how faults during the processing of a message map to particular HTTP status codes and how the semantics of HTTP status codes map to Web service invocations.

SOAP 1.1 Differences: Status Codes

In SOAP 1.1, the HTTP binding specified that if a fault was returned in an HTTP response, the status code had to be 500 (server error). This worked, but it didn't allow systems to use the inherent meaning in the HTTP status codes—400 means a problem with the sender, 500 means a problem with the receiver, and so on. SOAP 1.2 resolves this issue by specifying a richer set of fault codes; for example, if a soapenv:Sender fault is generated, indicating a problem with the request message, the engine should use the 400 HTTP status code when returning the fault. Other faults generate a 500, as in SOAP 1.1.

The HTTP binding also implements two abstract features, which are described next.

The SOAP Action Feature

In the SOAP 1.1 HTTP binding, you were required to send a custom HTTP header called SOAPAction along with SOAP messages. The purpose of this header was twofold: to let any system receiving the message know that the contents were SOAP and to convey the intent of the message via a URI. In SOAP 1.1, the first purpose was necessary because the media type was text/xml; since that media type could carry any XML document, processors needed to look inside the XML (which might involve an expensive parse) to check if it was a SOAP envelope. The SOAPAction header allowed them to realize this was a SOAP message and perhaps make decisions about routing or logging based on that knowledge. The presence of the header was enough to indicate that it was SOAP, but the URI could also convey more specific meaning, abstractly describing the intent of the message. Many implementations use this URI for dispatching to a particular piece of code on the backend, especially when using document-style SOAP. For example, you might send a purchase order as the body contents to two different methods—one called submitPO() and the other called validatePO(). Since the XML is the same in both cases, you could use the value of the SOAPAction URI to differentiate.

SOAP 1.2 uses the application/soap+xml media type, and the SOAPAction header is no longer needed to differentiate SOAP traffic from other XML documents moving across HTTP connections. But a lot of people still want a standard way to indicate a message's purpose outside of the SOAP envelope. The features and properties mechanism described earlier seemed like a perfect fit for an abstract feature.

The SOAPAction feature can be made available for any binding that uses the application/soap+xml media type to send its messages. The definition of that media type (which you can find in the glossary) specifies an optional action parameter, which is used in SOAP 1.2 instead of an HTTP-specific header to carry the SOAPAction URI. The feature has a single property, http://www.w3.org/2003/05/soap/features/ action/Action. When this property is given a URI value, the spec indicates that the binding that implements the feature must place the value into the action parameter. So, if the property had the value http://example.com/myAction at the sender, the message would start like this (assuming the HTTP binding):

POST /axis/SomeService.jws
Content-Type: application/soap+xml; charset=utf-8; 
_action="http://example.com/myAction"
...rest of message...

On the receiving side, a node receiving a message with an action parameter over a binding that supports the SOAP Action feature is required to make the value of the action parameter available in the http://www.w3.org/2003/05/soap/features/action/Action property.

The Web Method Feature

Normal SOAP exchanges across HTTP use the POST HTTP verb. However, sometimes other HTTP methods are more appropriate for a given situation. For instance, when you use the SOAP Response MEP, you're often making a state query, which in HTTP is modeled with the GET verb. If you only allowed POST, you would be forcing HTTP into a particular limited set of uses (purely as a transport). Therefore, in an effort to allow developers to better integrate the semantics of SOAP with the semantics of HTTP, the Web Method Feature (defined in part 2 of the spec) was born.

This feature defines a single property, http://www.w3.org/2003/05/soap/features/web-method/Method, which contains one of the words GET, POST, PUT, or DELETE (although other values may be supported later). When sending a message, the HTTP binding will use the verb specified in this property instead of the default POST. This is most often used in concert with the SOAP Response MEP to implement REST semantics.

Right now this feature is only relevant to HTTP; but if other bindings are developed to underlying protocols with REST-like semantics, it would be available for them as well.

InformIT Promotional Mailings & Special Offers

I would like to receive exclusive offers and hear about products from InformIT and its family of brands. I can unsubscribe at any time.

Overview


Pearson Education, Inc., 221 River Street, Hoboken, New Jersey 07030, (Pearson) presents this site to provide information about products and services that can be purchased through this site.

This privacy notice provides an overview of our commitment to privacy and describes how we collect, protect, use and share personal information collected through this site. Please note that other Pearson websites and online products and services have their own separate privacy policies.

Collection and Use of Information


To conduct business and deliver products and services, Pearson collects and uses personal information in several ways in connection with this site, including:

Questions and Inquiries

For inquiries and questions, we collect the inquiry or question, together with name, contact details (email address, phone number and mailing address) and any other additional information voluntarily submitted to us through a Contact Us form or an email. We use this information to address the inquiry and respond to the question.

Online Store

For orders and purchases placed through our online store on this site, we collect order details, name, institution name and address (if applicable), email address, phone number, shipping and billing addresses, credit/debit card information, shipping options and any instructions. We use this information to complete transactions, fulfill orders, communicate with individuals placing orders or visiting the online store, and for related purposes.

Surveys

Pearson may offer opportunities to provide feedback or participate in surveys, including surveys evaluating Pearson products, services or sites. Participation is voluntary. Pearson collects information requested in the survey questions and uses the information to evaluate, support, maintain and improve products, services or sites, develop new products and services, conduct educational research and for other purposes specified in the survey.

Contests and Drawings

Occasionally, we may sponsor a contest or drawing. Participation is optional. Pearson collects name, contact information and other information specified on the entry form for the contest or drawing to conduct the contest or drawing. Pearson may collect additional personal information from the winners of a contest or drawing in order to award the prize and for tax reporting purposes, as required by law.

Newsletters

If you have elected to receive email newsletters or promotional mailings and special offers but want to unsubscribe, simply email information@informit.com.

Service Announcements

On rare occasions it is necessary to send out a strictly service related announcement. For instance, if our service is temporarily suspended for maintenance we might send users an email. Generally, users may not opt-out of these communications, though they can deactivate their account information. However, these communications are not promotional in nature.

Customer Service

We communicate with users on a regular basis to provide requested services and in regard to issues relating to their account we reply via email or phone in accordance with the users' wishes when a user submits their information through our Contact Us form.

Other Collection and Use of Information


Application and System Logs

Pearson automatically collects log data to help ensure the delivery, availability and security of this site. Log data may include technical information about how a user or visitor connected to this site, such as browser type, type of computer/device, operating system, internet service provider and IP address. We use this information for support purposes and to monitor the health of the site, identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents and appropriately scale computing resources.

Web Analytics

Pearson may use third party web trend analytical services, including Google Analytics, to collect visitor information, such as IP addresses, browser types, referring pages, pages visited and time spent on a particular site. While these analytical services collect and report information on an anonymous basis, they may use cookies to gather web trend information. The information gathered may enable Pearson (but not the third party web trend services) to link information with application and system log data. Pearson uses this information for system administration and to identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents, appropriately scale computing resources and otherwise support and deliver this site and its services.

Cookies and Related Technologies

This site uses cookies and similar technologies to personalize content, measure traffic patterns, control security, track use and access of information on this site, and provide interest-based messages and advertising. Users can manage and block the use of cookies through their browser. Disabling or blocking certain cookies may limit the functionality of this site.

Do Not Track

This site currently does not respond to Do Not Track signals.

Security


Pearson uses appropriate physical, administrative and technical security measures to protect personal information from unauthorized access, use and disclosure.

Children


This site is not directed to children under the age of 13.

Marketing


Pearson may send or direct marketing communications to users, provided that

  • Pearson will not use personal information collected or processed as a K-12 school service provider for the purpose of directed or targeted advertising.
  • Such marketing is consistent with applicable law and Pearson's legal obligations.
  • Pearson will not knowingly direct or send marketing communications to an individual who has expressed a preference not to receive marketing.
  • Where required by applicable law, express or implied consent to marketing exists and has not been withdrawn.

Pearson may provide personal information to a third party service provider on a restricted basis to provide marketing solely on behalf of Pearson or an affiliate or customer for whom Pearson is a service provider. Marketing preferences may be changed at any time.

Correcting/Updating Personal Information


If a user's personally identifiable information changes (such as your postal address or email address), we provide a way to correct or update that user's personal data provided to us. This can be done on the Account page. If a user no longer desires our service and desires to delete his or her account, please contact us at customer-service@informit.com and we will process the deletion of a user's account.

Choice/Opt-out


Users can always make an informed choice as to whether they should proceed with certain services offered by InformIT. If you choose to remove yourself from our mailing list(s) simply visit the following page and uncheck any communication you no longer want to receive: www.informit.com/u.aspx.

Sale of Personal Information


Pearson does not rent or sell personal information in exchange for any payment of money.

While Pearson does not sell personal information, as defined in Nevada law, Nevada residents may email a request for no sale of their personal information to NevadaDesignatedRequest@pearson.com.

Supplemental Privacy Statement for California Residents


California residents should read our Supplemental privacy statement for California residents in conjunction with this Privacy Notice. The Supplemental privacy statement for California residents explains Pearson's commitment to comply with California law and applies to personal information of California residents collected in connection with this site and the Services.

Sharing and Disclosure


Pearson may disclose personal information, as follows:

  • As required by law.
  • With the consent of the individual (or their parent, if the individual is a minor)
  • In response to a subpoena, court order or legal process, to the extent permitted or required by law
  • To protect the security and safety of individuals, data, assets and systems, consistent with applicable law
  • In connection the sale, joint venture or other transfer of some or all of its company or assets, subject to the provisions of this Privacy Notice
  • To investigate or address actual or suspected fraud or other illegal activities
  • To exercise its legal rights, including enforcement of the Terms of Use for this site or another contract
  • To affiliated Pearson companies and other companies and organizations who perform work for Pearson and are obligated to protect the privacy of personal information consistent with this Privacy Notice
  • To a school, organization, company or government agency, where Pearson collects or processes the personal information in a school setting or on behalf of such organization, company or government agency.

Links


This web site contains links to other sites. Please be aware that we are not responsible for the privacy practices of such other sites. We encourage our users to be aware when they leave our site and to read the privacy statements of each and every web site that collects Personal Information. This privacy statement applies solely to information collected by this web site.

Requests and Contact


Please contact us about this Privacy Notice or if you have any requests or questions relating to the privacy of your personal information.

Changes to this Privacy Notice


We may revise this Privacy Notice through an updated posting. We will identify the effective date of the revision in the posting. Often, updates are made to provide greater clarity or to comply with changes in regulatory requirements. If the updates involve material changes to the collection, protection, use or disclosure of Personal Information, Pearson will provide notice of the change through a conspicuous notice on this site or other appropriate way. Continued use of the site after the effective date of a posted revision evidences acceptance. Please contact us if you have questions or concerns about the Privacy Notice or any objection to any revisions.

Last Update: November 17, 2020