WebReference.com - Chapter 30 of Curl Programming Bible, from John Wiley & Sons (1/8)

[next]

Curl Programming Bible, chapter 30

Curl and Web Services

In This Chapter:

Understanding the Simple Object Access Protocol (SOAP)
Calling Web services from Curl
Creating custom mappings between XML and Curl types
Troubleshooting SOAP calls

Web services coupled with Curl provide a new and powerful way to write Web applications. Curl enhances the user experience by harnessing the power of the client computer. Web services provide a language-independent, platform-independent mechanism for making server resources available across the Web. Curl's SOAP support makes it easy to call Web services from Curl.

Web services can vary in complexity. A Web service can be as simple as providing a stock quote. Or a Web service could provide a more complex function such as processing a credit card transaction. Many vendors are providing mechanisms to deploy Web services that allow developers to compose applications from code written in different languages running on different platforms.

Most Web services take the form of a remote procedure call (RPC). RPCs are much like language or local procedure calls except the code that executes as a result of an RPC may be located anywhere on the Internet. Like language procedure calls, RPCs have a procedure or operation name. And like language procedure calls, they may have arguments. Each argument is either an input argument or output argument. Input arguments are values passed between the caller and remote procedure. Output arguments are returned from the remote procedure to the caller.

Web Service Specifications

Most Web service specifications are being developed under the auspices of the World Wide Web Consortium (https://www.w3.org). The specification will evolve over time. However, the current versions of the specifications (SOAP 1.1 and WSDL 1.1) have been widely accepted and implemented so interoperable Web services are a reality today.

SOAP

Curl provides support of the Simple Object Access Protocol (SOAP) to invoke Web services. SOAP specifies

What is in a message and how to process it
How to encode application data
How to represent remote procedure calls and responses
The binding between it and the underlying protocol

It is necessary to understand the basics of the SOAP protocol to write custom marshalers and unmarshalers for complex types (more on that later). And knowledge of the SOAP protocol comes in handy when troubleshooting failures in SOAP calls.

A SOAP message is an XML document. Like all XML documents, a SOAP message has a single root element. The root element of a SOAP message is the SOAP Envelope. The SOAP Envelope must contain a single SOAP Body element. And the SOAP Envelope may contain a single SOAP Header element. If the SOAP Header element is present, it must precede the SOAP Body element. So, a SOAP message has the form:

<SOAP-ENV:Envelope 
 xmlns:SOAP-ENV="https://schemas.xmlsoap.org/soap/envelope">
	<SOAP-ENV:Header>
		Â
	</SOAP-ENV:Header>
	<SOAP-ENV:Body>
		Â
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The Envelope, Header, and Body element names are in the namespace https://schemas.xmlsoap.org/soap/envelope. The Body element provides a mechanism to pass mandatory information between sender and receiver. In the case of RPC, the Body element contains the arguments passed between the caller and the Web service. The Header element provides a mechanism for extending a SOAP message. Examples of extensions that the Header element might be used for are authentication and session management.

SOAP defines encoding rules used to pass application data to the client and Web ser-vice. The encoding rules bridge the differences among programming languages, and machine representation of data. The encoding rules are based on a type system that is a generalization of features common to the type systems of programming languages. In SOAP, a type is either a simple (scalar) type or a compound type com-posed of several parts, each with a type. Examples of simple types are int, float, and string. Examples of compound types are arrays and structs. Values of simple types are encoded as XML character data. Values of compound types are encoded as a sequence of elements. For structs, the element name identifies the field of the struct. Here is an XML fragment showing what a struct looks like in a SOAP message:

<IP>167.216.248.234</IP>
<Hostname>www.curl.com</Hostname>

The field names of the struct are IP and Hostname. The value of the IP field is 167.216.248.234, and the value of the Hostname field is www.curl.com. For arrays, the element name is irrelevant. Its members are distinguished by their ordinal position. Here is an XML fragment showing how an array is represented in a SOAP message:

<item>curlicue</item>
<item>whorl</item>
<item>ringlet</item>
<item>roll</item>
<item>scroll</item>
<item>gyre</item>
<item>coil</item>
<item>whorl</item>
<item>ringlet</item>
<item>lock</item>

This example is an array of ten values. The first value is curlicue, the second value is whorl, and so on. item is used as the tag name for the element surrounding each value.

An RPC in SOAP consists of a SOAP request message and a SOAP response message. The request message is sent from the client to the Web service. And the response message is sent from the Web service back to the client. The request message contains the procedure name and input arguments. The response message contains the output arguments.

The Body element of the SOAP request message contains the operation name and the input arguments. The Body element contains a single element whose name is the procedure or operation name. Contained within the single element are the input arguments. Each input argument is contained within an element. The name of the element is the name of the argument. Here is what the SOAP body would look like for a call to a procedure named getQuote with a single input argument named symbol, and with string GE being the value of the input argument:

<SOAP-ENV:Body>
<getQuote>
<symbol>GE</symbol>
</getQuote>
</SOAP-ENV:Body>

NOTE: In SOAP RPC, all arguments have names. The argument names are used as element names in the SOAP message.

The response message has a structure similar to the request message. The Body element of the SOAP response message contains a single element. Contained within the single element are the output arguments. Each output argument is contained within an element. The name of the element is the name of the argument. Here is response message corresponding to the above request:

<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:soap='https://schemas.xmlsoap.org/soap/envelope/' xmlns:xsi='https://www.w3.org/2001/XMLSchema-instance' xmlns:xsd='https://www.w3.org/2001/XMLSchema' xmlns:soapenc='https://schemas.xmlsoap.org/soap/encoding/' soap:encodingStyle='https://schemas.xmlsoap.org/soap/encoding/'>
<soap:Body>
<n:getQuoteResponse xmlns:n='urn:xmethods-delayed-quotes'>
<Result xsi:type='xsd:float'>37.08</Result>
</n:getQuoteResponse>
</soap:Body>
</soap:Envelope>

The element contained within the SOAP Body follows the usual convention of appending Response to the operation name. The response contains one output argument named Result with a value of 37.08. Note, the Result element includes an attribute indicating the type of the argument. The elements surrounding arguments in SOAP messages may (but are not required to) contain type attributes specifying the type of the argument.

SOAP messages use the Hypertext Transfer Protocol (HTTP) as the underlying protocol. HTTP is the same protocol Web browsers and Web servers use to communicate. The SOAP message is sent to a SOAP server identified by its URL just as a Web page is identified by its URL. Unlike most Web page requests, the SOAP request uses the HTTP POST method rather than the GET method. An HTTP POST request has a request body. In the case of a SOAP call, the request body is the SOAP message, an XML document. In addition, all SOAP requests over HTTP contain a SOAPAction HTTP header field. The form of the HTTP header field is SOAPAction: "<string>" where <string> depends on the SOAP operation being called. The SOAPAction header field may be used by servers such as firewalls to filter SOAP requests.

NOTE: Both HTTP requests and SOAP messages have headers and bodies. It is easy to confuse them. SOAP messages are passed in HTTP request (and response) bodies. So, the SOAP header is contained in the HTTP body.

In the rest of this chapter, we will refer to the SOAP Header element as the SOAP Header. Similarly, we will refer to the SOAP Body element as the SOAP Body.

WSDL

Web Service Description Language (WSDL) is an XML-based language used to describe SOAP operations. The WSDL file for a Web service describes its interface. For SOAP operations accessible through HTTP, the WSDL includes the URL of the SOAP server, the value to include in the SOAPAction HTTP header field of the SOAP request, the operation name, and the names and descriptions of the operation's input and output arguments.

NOTE: Calling WSDL an XML-based language means that WSDL files are XML documents, just as SOAP messages are XML documents.

UDDI

The Universal Description, Discovery, and Integration (UDDI) project is an industry initiative to create a framework for describing services, discovering businesses, and integrating business services using the Internet. UDDI exposes a SOAP interface for registering and searching business information, including Web services that a business makes available on the Internet.

The concept is that businesses register themselves with UDDI, and other businesses search UDDI when they want to procure a product or service. These operations can be performed by a SOAP client. In the case of a business that exposes a Web service, the UDDI entry for the business would contain the URL of the WSDL describing the interface to the service. The information in the WSDL could then be used to invoke the Web service.