You can think of this project as ‘SOAP lite’. It shows how one can build out an web service API that works along RESTful practices – but has a way to catalogue what calls are available. Like SOAP it’s possible to connect to the web service and create a stub on the fly which can be used to call the exposed web service methods.

Unlike SOAP it’s not a heavy implementation. These are the key points:

• Type information is not overwhelming specified in the same detail as it is for SOAP.  Over specifying type information is what makes SOAP brittle.
• The methods can be called using any HTTP client without requiring a specialized client to do it. Unlike SOAP it’s not hard to call these methods – there aren’t lots of bizarre little rules to make things not work.
• With SOAP it’s necessary for the client to pull the whole WSDL (Web Service Definition Language) file at once and parse it in it’s entirety which makes SOAP slow and cumbersome. The design of this approach means we can optimize it to only pull down some of the information.
• Documentation of the web API is foremost in the design.  The emphasis is on making it easy for a human being to understand rather than a computer – since (for now at least) human beings write code.

We’re actively looking for one of our OEM partners to work with in terms of putting this into the field in a real application – there are some optimizations and tweaks that we could make to turn this into something that will really turn this into a showcase of how integration can be done.

If you think about it – this is the ultimate:

• A clear public API for an application –  So upgrading is easy.
• Only small amounts of custom external Lua code needed for each custom interface – easy to maintain.
• Simple to learn – easy to scale teams up and down to interface a specific product.
• Complete random access to the data model of your application – perfect control for the integration engineer.

The approach can be layered on top of any pre-existing application – SOAP and .NET, Microsoft Azure, Java JSP pages, Ruby on Rails since you can craft this web service as an intermediary to those backend layers.

The service has recently hit the next phase of evolution with a whole raft of extra functionality.  You can grab it with the channel manager by getting the channels called Webservice 1 and 2.

The web service now allows you to edit the help.  The cool thing about this that it suddenly has become very easy to write help for any Iguana translator module.  The editor hasn’t been styled yet but it’s quite functional, here’s the view mode:

And here’s the edit mode:

If for nothing else it’s a great tool to write help for your own modules.  Currently it stores the help in JSON files as part of the project.

We’ve had a go at wrapping up the RESTful API from a simple CRM application called Highrise from Basecamp.  The web service supports methods that can be accessed like a normal RESTful webservice like so:

http://localhost:6543/webservice/company/app?name=Acme&background=A+generic+company.

But where it really get’s fun is where you can connect to the service using a simple Lua client Kevin wrote which will create Lua functions on the fly which have help defined.  These allow an interface programmer to auto-discover the methods of the web service, call them and see their help within the translator.  Here’s an example screen shot:

This shows the best practice in building out a really intuitive easy to use API for integration into an application.

If you want to have kick the tyres you can try it right now – this prototype is already in the community apps repository – just get the Channel Manager and you’ll be able to import it.  See what you think.

The next stages for this project will involve using the new DBS grammar format to make it easy to supply structured data which can used to populate records with these web service calls. There are definitely performance optimizations we could make to keep things fast with even a big API.

One question which comes up is how does this compare to something like RAML?  RAML is a standard which also attempts to go down the SOAP path for RESTful based JSON APIs by having a standard for defining them based on the YAML format.  RAML makes the same mistakes as SOAP in my opinion for these reasons:

1. It goes overboard in specifying low level details about what kind of HTTP methods a web server supports. I don’t think this makes much sense. If this is an API to my EMR then I want to get information related to the domain of this EMR – I don’t want to thinking in terms of whether or not this interface supports HTTP ‘PUT’, ‘GET’, ‘DELETE’ operations. HTTP return code specified in exhaustive detail isn’t useful. This is all low level nonsense that shouldn’t matter to me. A decent RESTful interface should work with both POST or GET and the parameters should be possible to pass as either GET or POST parameters.  While calling a RESTful API of an EMR I should be working at higher level of abstraction.
2. It is not valid thinking just because you have a excessively complex ‘API contract’ that the underlying implementations will conform to that contract and that software out there will correctly implement all the nuances of that contract.  It gives a false level of security. Apply the KISS principle.
3. More complexity for features that don’t offer value means more mental bandwidth consumed by cruft that doesn’t add value to your core task.  It’s a common enterprise software ‘anti-pattern’ where developers waste their time become experts of complex technology of the day and make bloated software instead of putting that effort into making their end products easy to use and fixing the core problem.  Put it another way – Apple would never have invented the iPhone if they had left it up to a couple of ‘UML architects’…
4. Also more complexity means less time to optimize performance since effort is consumed by implementing all those features that didn’t add value in the first place.
5. Complex standards are hard to make truly inter-operable. What happens with these is that one implementation becomes the so called ‘defacto’ standard. That’s awesome if you are the vendor that invented and/or promoted the complex standard. Not so great if you bought into the technology in the first place.  It’s a game which gets played out again and again and there always seems to be a new generation of people that fall for it. RAML looks very much positioned to tie you into a particular vendor which is the lead contributor to this standard.

It all reminds me of back in 1995 when COM, DCOM and ActiveX were all the rage and the amount of effort I spent learning about single apartment versus multi-apartment threading models thinking there was some deep wisdom in those choices that mastery of would make me an expert programmer.  Eh no – just arbitrary meaningless complexity for it’s own sake.

To follow progress and talk about this app please subscribe or talk on this forum.