Saturday, 5 October 2013

the coming out of skysail

I've been playing with this little pet project of mine for quite a while now. I did learn a lot, mainly by making a huge number of mistakes ;)

By now, things start becoming a little bit more stable (well, we're still in pre-alpha to be honest). Nevertheless, I started with some documentation and I am ready to share my ideas, hoping for feedback.

The coming out of skysail

For starters, I want to provide a 10.000 feet view of skysail:

Looks like the typical input-process-output chain - sure, it's IT after all ;)

So, what's special about this? First of all, the skysail server deals with RESTful requests only (please note that this is not about restful web services). What seems like a restriction really adds value, as explained later.

The request will get processed (skysail will take care of authentication, authorization, logging, persistence and the like in a generic way) and return a response.

This response is a representation of the answer to that request. The specific format of the answer (that is, the response representation) depends on the request itself - asking for a JSON-formatted response will give you a JSON string. This powerful feature is build into the http protocol itself, called content negotiation.

An example

Let's assume you have a skysail server installation at, running on port 8080, and this installation provides a RESTful "notes" application, i.e. the following paths are mapped to resources dealing with the following requests:

 /notes          -> mapped to NotesResource
 /notes/{noteId} -> mapped to NoteResource

Now, by typing in your browser, what you do is to initiate a GET request to that URL, which is dealt with by your skysail installation and mapped to the second resource, NoteResource.

NoteResource reacts to the request according to the business logic defined in the notes application. Typically, assuming you've been authenticated and have the proper permissions, the application will get the note with id 27 from its persistence store, format it according to the request, and deliver it:

    "message": "Note #27",
    "success": true,
    "data": [
            "pid": 27,
            "parent": null,
            "title" : "myNote",
            "content" : "some content",
            "owner": {

Please note that skysail server itself is not capable of dealing with notes or any other business entities, this is the task of dedicated OSGi-bundles deployed into skysail server. Using OSGi is the only way to properly deal with all the requirements (in terms of modularization and shared services).


As described, skysail is a RESTful "business server" focusing on the business logic. This is, IMHO, a reasonable abstraction, as it really separates the representation of entities (the GUI) from the logic performed in the back-end.

Like this, it is very easy to develop various clients (think about a web application, a rich client and multiple mobile apps), all communicating with the same business server. Those clients could be written in any language, too. The only thing they'd have to suport is the HTTP protocol (and understand json).

So, the restriction on dealing with RESTful requests only gives you a chance to really decouple clients and server and provide the most generic interface, using the standard HTTP methods like GET, POST, PUT and DELETE.