JSON Service Mapping Descriptions
We decided that one of the biggest things missing from ajaxToaster was formal descriptions of the web services. Historically WSDL has been used to describe the operations and input/output messages for WS web services, but If you’ve ever looked at a WSDL document, you’ll understand why we have decided to implement Kris Zyp’s JSON service-mapping-description proposal instead.
This is pretty straightforward and easy to understand, and overall we’re happy with the concept, but is not without it’s quirks and ambiguities. For instance, there isn’t a distinction between “services” and operations. There isn’t any way to tell how parameters are passed into the service on a POST - in the post body or as url parameters.
It is also not so simple to use the resulting object from javascript. Here’s an example of a service description:
"services": {
"foo": {
"transport": "GET",
"target": "executeFoo.php",
"parameters": [
{"name":"paramOne", "type": "string"},
{"name":"paramTwo", "type": "integer", "default": 5},
{"name":"paramThree", "type": "integer", "optional": true}
]
},
"add": {
"transport": "POST",
"envelope": "JSON-RPC-2.0",
"additionalParameters": {"type": "integer", "default": 0},
"parameters": [
{"type": "integer", "default": 0},
{"type": "integer", "default": 0}
]
}
}
}
This SMD contains two services, “foo” and “add”. Note that the services aren’t in an array, so the properties for a particular service can only be referred to directly if you already know the name of the service e.g. alert(services.foo.transport);
Most of the time you won’t know this, so you have to resort to tricks - e.g using eval….
for (x in services) {
servicedetails = eval("services."+x);
alert(servicedetails.transport);
}
Complaints aside, we are looking forward to adding this to the next version of AjaxToaster, as it will make documenting and testing services much easier.
