Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss

tclws (2.4?) changes to support REST/JSON, optional arguments, and more

83 views
Skip to first unread message

Jeff Lawson

unread,
Apr 5, 2017, 4:26:11 PM4/5/17
to
As a part of FlightAware's use of tclws (Web Services for Tcl), we have developed some significant improvements to tclws that allow it to support returning REST/JSON responses from any function that had previously been SOAP-only.

All of these changes are currently in this branch for a proposed version 2.4 of tclws:
http://core.tcl.tk/tclws/timeline?r=fwr-jsonrest-changes


Included is support for optional structure members (minOccurs=0 in the WSDL) if you define the datatype with a suffixed "?" character. (This is in the spirit of the existing tclws datatype syntax of using the "()" suffix to indicate arrays, and also in the style of Swift optional arguments.)

Additionally, if you specify -enforceRequired Y in the service definition you will receive an error if any of your procs accidentally forget to return a structure member that had not been designated optional. The default is -enforceRequired N, which will preserve the prior behavior of simply returning the result anyways with the missing members absent.

Basic input argument validation can be requested by specifying -verifyUserArgs Y in the service definition.

We've also added a -errorCallback option to the service definition to allow your code to customize any exceptions before they are actually sent back to the caller. (We use this functionality to internally log caller-induced errors and to customize the HTTP response headers and status codes in certain cases.)

Service documentation can also be emitted into a JSON format, rather than only HTML or WSDL. We use this to provide a more complex client-side presentation of the documentation than would be possible with only custom CSS against the HTML: https://flightaware.com/commercial/flightxml/explorer/



Internally, we've changed many of the procs in ::WS::Server to define a new "flavor" variable throughout that specifies "soap" or "rest" mode, and made ::WS::Server::callOperation accept that flavor as an optional argument. If the flavor is not specified, then soap is still assumed by default in order to preserve compatibility with existing tclws users.

In order to serialize the JSON responses, we added a dependency on our yajl-tcl package, but that is only required when you initiate a request in the "rest" flavor: https://github.com/flightaware/yajl-tcl

Our use case has only required us to accept FORM arguments and return JSON responses for everything, so we haven't implemented logic to parse any input arguments that are passed in as JSON serialized data, but this might be an area of future exploration for someone.

Here's a bit of code showing how we initially start up this mode in Apache Rivet, which is actually pretty similar to how you'd use tclws in SOAP mode from Apache Rivet:


# Capture the info from the request into an array.
load_headers hdrArray
set sock [pid]; # an arbitrary value
array unset ::Httpd$sock

# Prepare the CGI style arguments into a list
load_response formArray
set opname $formArray(call)
unset formArray(call)
set queryarg [list $opname [array get formArray]]

# Invoke the the method
array set ::Httpd$sock [list query $queryarg ipaddr [env REMOTE_ADDR] headerlist [array get hdrArray]]

# Invoke the method in REST mode.
set result [catch {::WS::Server::callOperation $svcname $sock -rest} error]
array unset ::Httpd$sock
if {$result} {
headers numeric 500
puts "Operation failed: $error"
abort_page
}


Gerald Lester recommended that I post here describing these changes and solicit feedback before we merge my branch. With the world increasing embracing REST services over SOAP, these changes will likely make tclws relevant to many more users.



- Jeff

Harald Oehlmann

unread,
Apr 7, 2017, 4:11:08 AM4/7/17
to
Hi Jeff,
Thank you, Gerald !

The code looks like a big step and extension.

Your text is now in a ticket here:
https://core.tcl.tk/tclws/tktview/9c6ff35e394cfed95235b8a7871cb340135bf940

Consider to add comments to this ticket.

I would appreciate any help text enhancements before the merge.

Sorry, no technical comment on the patch from my side...

Thanks,
Harald

Harald Oehlmann

unread,
Apr 7, 2017, 6:05:29 AM4/7/17
to
Am 07.04.2017 um 10:11 schrieb Harald Oehlmann:
> Hi Jeff,

Sorry, it was Jeff, not Gerald...

0 new messages