Choosing an Interface for Web Service Access

Data services — that is, your XQuery exposed as a Web service — deployed on the XQueryWebService framework can be accessed using two techniques:

• Simple Object Access Protocol (SOAP)
• Representational State Transfer (REST)

SOAP is a W3C Recommendation and has been around for nearly a decade. SOAP is usually the more appropriate of the two techniques for complex processing or when security (exposing sensitive data) is an issue. But REST is gaining popularity for a couple of reasons, including minimal requirements on the client, and an interface — the URI — that is straightforward and well-understood.

Let's take a look at a simple XQuery, emp.xquery, which we have saved to our local XQuery directory (c:\MyQueryDir, as defined inweb.xml). When run against the SQL Server pubs sample database, this XQuery returns an employee record given an ID ("A-C71970F").

	(: emp.xquery :)
	
declare variable $id as xs:string external;

<root>
{
	for $employee in collection("pubs.dbo.employee")/employee
	where $employee/emp_id = $id
	return $employee
}
</root>

Using REST

Using REST, this XQuery can be executed from any Internet browser using just this URL:

http://localhost/XQueryWebService/emp.xquery?id=A-C71970F

Notice that the employee ID ("id=A-C71970F") is visible in the URL.

The result would look something like this:

<dd:Output xmlns:dd="http://www.datadirect.com">
	<root>
		<employee>
			<emp_id>A-C71970F</emp_id>
			<fname>Aria</fname>
			<minit/>
			<lname>Cruz</lname>
			<job_id>10</job_id>
			<job_lvl>87</job_lvl>
			<pub_id>1389</pub_id>
			<hire_date>1991-10-26T00:00:00</hire_date>
		</employee>
	</root>
</dd:Output>

Using SOAP

Using SOAP, on the other hand, requires submitting the following SOAP request (XML):

<?xml version="1.0"?>
<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
	<SOAP-ENV:Body>
		<dd:emp xmlns:dd="http://www.datadirect.com">
			<dd:id>A-C71970F</dd:id>
		</dd:emp>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The result, shown here, is pretty much the same as the one returned using REST, only now it is "wrapped" in the SOAP envelope:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
	<SOAP-ENV:Body>
		<dd:Output xmlns:dd="http://www.datadirect.com">
			<root>
				<employee>
					<emp_id>A-C71970F</emp_id>
					<fname>Aria</fname>
					<minit>
					</minit>
					<lname>Cruz</lname>
					<job_id>10</job_id>
					<job_lvl>87</job_lvl>
					<pub_id>1389</pub_id>
					<hire_date>1991-10-26T00:00:00</hire_date>
				</employee>
			</root>
		</dd:Output>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Next Steps

The XQueryWebService framework includes some simple tools that let you test the Web service operations you include in your applications. These tools are covered in the next section.