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.

Sample XQuery

Let's take a look at emp.xquery, which we have saved to our local XQuery directory (c:\MyQueryDir, as defined in web.xml).

declare variable $id as xs:string external; 
 
<root> 
{ 
    for $employee in collection("pubs.dbo.employee")/employee 
    where $employee/emp_id = $id 
    return $employee 
} 
</root> 

When run against the SQL Server pubs sample database, this XQuery returns an employee record given an ID ("A-C71970F").

Using REST

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

 http://examples.xquery.com/employee-lookup/emp.xquery?id=A-C71970F 

Notice that with REST, the employee ID ("id=A-C71970F") is visible in the URI.

The result looks 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):

<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.