Now that we understand the convenience of simplicity let's try to add complexity without losing the basic essence.
Real life sample (well, sort of)
<request>
<call class="Usps.Address" method="Validate">
<var type="object">
<address>
<street>123 NW ST.</street>
<street>Suite 123</street>
<city>Miami</city>
<state>FL</state>
<postal>33123</postal>
</address>
</var>
</class>
</request>
Multiple calls:
<request>
<call library="Math" class="Samples" method="Subtract">
<var type="int">5</var>
<var type="int">3</var>
</call>
<call library="Math" class="Samples" method="Multiply">
<var type="int">5</var>
<var type="int">3</var>
</call>
<call library="Math" class="Samples" method="Divide">
<var type="int">5</var>
<var type="int">0</var>
</call>
</request>
<response>
<data>
<var type="int">2</var>
</data>
<data>
<var type="int">15</var>
</data>
<data>
<error code="123">Division by zero</error>
</data>
</response>
When multiple calls are executed, the response packets are enclosed in data tags
Note: Although rare in some languages, a method can return mutiple parameters, like in Python.
Multiple calls with result reuse:
<request>
<call library="Math" class="Samples" method="Subtract">
<var type="int">5</var>
<var type="int">3</var>
</call>
<call library="Math" class="Samples" method="Multiply">
<var type="int">{result}</var>
<var type="int">3</var>
</call>
<call library="Math" class="Samples" method="Divide">
<var type="int">{response/data[1]/var}</var>
<var type="int">0</var>
</call>
</request>
<response>
<data>
<var type="int">2</var>
</data>
<data>
<var type="int">6</var>
</data>
<data>
<error code="123">Division by zero</error>
</data>
</response>
Note: Not implemented due to excesive complexity and few use cases
For result reuse in multiple calls we need to enclose the result keyword in curlies
Also, using xpath in curlies to get any var of the temporary xml tree of all calls executed at that point.
Callback:
If we need to asynchronously request a method and get the result sent to other URL:
<request id="12345678-1234-1234-1234-123456789012" reply="http://myCallback.php" >
<call library="Math" class="Samples" method="Subtract">
<var type="int">5</var>
<var type="int">3</var>
</call>
</request>
The response will be redirected to the URL in the "reply" attribute.
Ids are required for request/response coupling
<response id="12345678-1234-1234-1234-123456789012">
<data>
<var type="int">2</var>
</data>
</response>
Easy schemas:
<request reply="callbackURL" userid="" password="" id="guid">
<call library="Math" class="Samples" method="Add">
<var type="integer" name="anyName" direction="in|out">value</var>
:
</class>
:
<sql database="myData">
<command>Select * From ...</command>
<var type="integer" name="anyName" direction="in|out">value</var>
:
</sql>
:
</request>
<response id="guid">
<data>
<var type="int">2</var>
:
<error code="123">Division by zero</error>
:
</data>
:
</response>
Note: Userid and password are optional for authenticated methods
Note: Sql calls are under development (just a brain teaser)
Data types (Default type is string)
bool : true, false
stream : "any stream base64"
string : "Lorem ipsum"
int : 123
integer: 123 // same as above
number : 1234.567 // any real +/-
date : 2001/01/01
time : 2001/01/01 11:59:59
timeUTC: 2001/01/01T11:59:59.123 //UTC time
list :<var type="list">
<item>123</item>
<item>456</item>
<item>789</item>
</var>
map :<var type="map">
<item key="one" >123</item>
<item key="two" >456</item>
<item key="three">789</item>
</var>
object :<var type="object">
<customer>
<name>Jane Doe</name>
<phone>555-1234</phone>
<address>
<city>Miami</city>
<state>FL</state>
<postal>33123</postal>
</address>
</customer>
</var>
table :<var type="table">
<address>
<city>Miami</city>
<state>FL</state>
<postal>33123</postal>
</address>
<address>
<city>Boynton Bch</city>
<state>FL</state>
<postal>33124</postal>
</address>
<address>
<city>Delray Bch</city>
<state>FL</state>
<postal>33125</postal>
</address>
</var>
memo :<var type="memo">
<![CDATA[ "Whatever goes here <b>is ok</b> even non-escaped markup" ]]>
</var>
enum :<var type="enum">color.blue</var>
Did we miss one?
Opinions...
Standard specs mean notihng without standard procedures, policies and implementations.
1. There will be one entry point in every compliant server, auto-discoverable, preferably:
http://anyCompany.com/public/WebMethods.php
2. A public xml file will contain all methods available: WebMethods.xml
http://anyCompany.com/public/WebMethods.xml
<public>
<library name="Math">
<class name="Samples">
<method name="Subtract">
<request>
<var name="number1" type="int"/>
<var name="number2" type="int"/>
</request>
<response>
<var name="result" type="int"/>
</response>
</method>
:
</class>
:
</library>
:
</public>
3. Public system methods from a public class can help the user identify resources:
<request>
<call class="Public.Methods" method="GetMethods"/>
<call class="Public.Methods" method="GetSignature">
<var>Math.Divide</var>
</call>
</request>
Suggestions?
I told you it was going to be fun.
Thanks for your invaluable time.