Bayonne  GnuComm

ServerResponse Specification

Contents

• Introduction
• Examples of Use
• Error Responses
• Lists and Tables
• Concluding Remarks

Introduction

ServerResponse is a small XML dialect which can be used to offer web services with less complexity than XMLRPC. ServerResponse offers <serverResponse> XML replies to standard HTTP GET requests, which can include query options as part of the URI. The serverResponse document returned from the GET request is formatted in XML.

ServerResponse is related to XMLRPC, but without the use of explicit parametric types. All arguments and returned values are typeless. For this reason, the request can be made as a GET request with query arguments, rather than a POST with a XML-encoded document. The actual URI request also becomes the method being called.

Example of Use

Here is an example of serverResponse:

 GET /status.xml HTTP/1.0
 User-Agent: Any
 Host: 127.0.0.1
 ...

 HTTP/1.1 200 OK
 Connection: close
 Server: Bayonne/1.5.4
 Connection-Type: text/xml

 <?xml version="1.0"?>
 <serverResponse>
  <results server="bayonne" service="status">
   <result id="status" value="-- "/>
  </results>
 </serverResponse>

The <results> block tells us that there is one or more successful results. The <result> entry tells us what each result is (value) and what that result is associated with (id). Generally, the server will perform some operation when the query is received, and may return the result of that function as a <result>. The <results> tag also holds information on the server type that was responding, and the explicit service, which reconfirms the URI, or, in XMLRPC what would have been the “method” invoked. If one wishes to simply indicate some function was completed successfully without returning any additional status information, it is sufficient to return an empty <results></results> block to indicate this.

Error Responses

Here is an example of a HTTP response for an unknown URI:

 GET /unknown.xml HTTP/1.0
 User-Agent: Any
 Host: 127.0.0.1
 ...

 HTTP/1.1 404 Not Found
 Connection: close
 Server: Bayonne/1.5.4
 Connection-Type: text/xml

 <?xml version="1.0"?>
 <serverResponse>
  <faults server="bayonne" service="http">
   <fault id="code" value="404"/>
   <fault id="text" value="Not Found"/>
  </faults>
 </serverResponse>

In this case, like in XMLRPC, we get a fault response. This fault response indicates the service it is associated with is http serving, and that we received a 404 result. Faults can also occur as error results from requests to existing URI's which perform some operation that fails. The failure is returned as a <faults> response in place of <results>.

Lists and Tables

Lists and tables of results can also be returned through serverResponse. Here we have an example of such a service:

 GET /registrations.xml?driver=sip HTTP/1.0
 User-Agent: Any
 Host: 127.0.0.1
 ...

 HTTP/1.1 200 OK
 Connection: close
 Server: Bayonne/1.5.5
 Connection-Type: text/xml

 <?xml version="1.0"?>
 <serverResponse>
  <results server="bayonne" service="registrations">
   <lists id="registrations">
    <list id="registration">
     <item id="driver" value="sip"/>
     <item id="server" value="192.168.1.95"/>
     <item id="userid" value="291"/>
     <item id="access" value="friend"/>
     <item id="status" value="active"/>
    </list>
   </lists>
  </results>
 </serverResponse>

The <lists> container is much like the table container in HTML. The <list> section block is like a <struct> in XMLRPC or row in HTML. The item records are like the table details in HTML, and are used in place of a <result> to indicate they are part of the list.

Concluding Remarks

There are several advantages to be found in serverResponse over XMLRPC. First, we do not use POST with XML-encoded query parameters. Instead, we use a GET request. This means that a server offering server response does not require XML parsing code of any kind, which XMLRPC requires to validate the posted request document. Second, we eliminated the need to compute a Content-Length: This means the serverResponse reply can be generated free-form from an embedded service running a simple embedded HTTP service without having to pre-compute the length of the reply message, or pre-buffer the reply to be able to do so. While XMLRPC is designed around systems that will marshal strictly typed parametric data arguments and replies into function calls, serverResponse is very lightweight to support, and very easy for other existing web services to directly use.