Self describing web service and help editor

Have a look at this code snippet and tell me what makes this interesting:

local HelpData = help.get(hl7.parse)
local Server = {}
Server.parse = function(T) end
help.set{input_function=Server.parse, help_data=HelpData}

That it’s easy to provide per-function interactive help and code completion support that has nothing to do with the function’s required argument(s)? 😀

Jeff Drumm ◊ VP and COO ◊ HICG, LLC. ◊ http://www.hicgrp.com

So Eliot, what did you have in mind for an answer?

Jeff Drumm ◊ VP and COO ◊ HICG, LLC. ◊ http://www.hicgrp.com

Darn I wasn’t subscribed to the forum question even though I posted it.

The interesting thing here is the ease with which you can create a function on the fly and give it help data that drives help within the IDE and gives you the nice auto-completion of parameters it takes and so on.

Now where it really gets interesting is that you can send that data over a network…

You can have a webservice serve up a directory of calls it supports. Each call can describe it’s parameters and supply nice documentation and it’s possible to make a client module which off the following syntax:

local Client = webservice.connect{url="http://mywebservice:6544", username="fred", password="secret}

-- Client is now an object which has a whole bunch of methods which have been created
-- dynamically that have great auto-completion options and context sensitive help like this:
Client.patient.add{firstName="Fred", lastName="Smith"}


The concept is very similar to SOAP and WSDL but implemented in a very simple friendly way that gives the helpful parts without the incompatibility headaches of SOAP.

The first stage is done:

http://help.interfaceware.com/kb/self-describing-web-service

And now the next stage is done – the client is implemented and it’s possible to edit the help which makes this a very useful tool for authoring help for your Iguana lua functions.

So one of the next puzzles with how to push this project along is how do you make it easy to describe a data-structure that is easy to map data into.

i.e. in the case of Highrise there are two kinds of data entities – Contacts (people) and Companies. These entities have structured data which is associated with them. In the native Highrise API provided by Basecamp it doesn’t have a schema – we have XML records which are described but not all that easy to map data into and out of (well not soooo bad – but it could be better).

Now thanks to the efforts of Ram we now have a new tool in toolbox that gives us a light weight way to describe some simple grammars:

http://help.interfaceware.com/kb/introducing-database-schema-dbs-files

Now these grammars are meant to be for defining ‘tables’ but really if you look at the Highrise datamodel (in XML format) – see https://github.com/basecamp/highrise-api/blob/master/sections/data_reference.md#person

It’s not all that difficult to go ahead and express that data-structure in terms of this DBS schema format – the nice thing about the DBS format is that it’s lightweight (not much data to send over the wire). Effectively one could leverage it to describe structured data to include in a call to things like:

highrise.person.update

Instead of using the table schema to drive the creation of database inserts one simply could use it describe simple collections of data in JSON. So it make for an interface which is both very easy to use in Iguana but still using very generic code under the hood with simple easy to understand JSON.

I think it looks like a promising model.