Project: Yellowcake | IBM Lotus Notes/Domino REST API

02/11/2008 11:08 AM by Chris Toohey

The typical application architecture for a user client interacting with a Domino application is this:

Simply put, the user client accesses the Domino application - which has been designed/modified to account for the given user client type - with direct reads/writes to said Domino application. The application design requires that security, functional UI elements, and such be built directly into the given Domino application. This architecture is nothing new to Domino Developers, but can often cause issues when a given developer does not recognize the need for separation between data and functional application UI.

The more advanced application architecture for a user client interacting with a Domino application is this:

Basically, the user interacts with a conduit or API that allows an interaction point between applications. Now, this conduit/API is typically pretty hard coded - and you see that with the web service APIs that are out there today. Check out the Google Maps API, there are statically-defined API that allow for some pretty amazing extended functionality. The problem with this approach - you are often afraid to touch anything. The conduit app is fairly hard-wired, designed for this singular need (the given API). This can often restrict both development and administration efforts, as not only is it a chore to expand the scope of functionality in your Domino applications (and forget it if you need to bring in a fresh developer who is not familiar with the given conduit design...), but the admins can't easily move databases to other servers or directories without full-well knowing that it will break something, somewhere, at sometime!

Now what is Project: Yellowcake? Project: Yellowcake is, simply put, a configurable REST API for Domino applications.

I came up with this approach and thought that I had invented the wheel - only to have someone tell me that it was a REST API - or a Representational State Transfer API. So a public thanks to Nathan for that one!

So here are some specifics about just what Project: Yellowcake is, for those of you who are still reading this far into the post...

You - the Developer/Admin, can define an Application Profile. The Application Profile will contain information about the target Domino application - both server and database, as well as allow you to define a specific dbkey - which is to be used as a key for any interaction with this particular application. One of the best parts? Admins can move the database to another directory (or another server for that matter), and all you will need to do is update the Application Profile with the target Domino applications new location! (see that, it's ADMIN-friendly!!)

You can then create either a Query Template or a Save Template for your given Application Profile. While the names should prove the following description unnecessary...

Query Template:
You will define both Content Type (by default, you can return HTML, Plain Text, XML, CSS), the result set formatting, and a given appkey. When the given appkey is invoked - typically via a GET/POST of sorts, the Query Template Author-defined API arguments are passed to the REST API, returning a NotesDocumentCollection from the target database. The Query Template then will iterate through the collection, and merge your result set on-the-fly (think of a Mail Merge), and build your resultant markup.

Save Template:
You will define one of the only static API parameters - docid - and invoke the Save Template via (typically) the result of a Form element's processing agent. The Save Template will then iterate through a series of WebQuerySave-like events that will be evaluated against the target document (defined via a combination of the dbkey and the docid parameter). Currently, the trigger options are running in-line Formula, running an Agent in the target database, or redirecting to a specific URL.

I'll post a few more entries defining the real-world usages of Project: Yellowcake in the upcoming days... while I search for a private alpha team for testing this thing out while I clean up some things...

If you're interested in being on the angel-round private alpha team, please contact me. Otherwise, check back here for more details in the upcoming days...