One of the most important properties of the URIs/URLs is that you cannot say that the associated response (after a call to the URI) is a static resource or a dinamic one (generated after a possible complex process).

This indistinguishability of static resource vs. processed resource that URIs provide is the key point that RESTscape tries to exploit.

RESTscape focuses mainly in URIs that process resources. In virtue of its indistinguishability property, RESTscape explores how to chain URI processes so you can build fairly more complex processes than the individual ones.

The URI/URL as a web command

Look at the following URL:

This URL is pointing to a file served by or not? As we have said before, no one can say if there's a file or just an internal mapping to the following web command (that transforms a FO file into a PDF):

This is exactly the indistinguishability we were talking about. RESTscape project main interest is the web command aspect of the URI/URL, as the regular URL that serves a resource it is just a matter of mapping.

Web command structure

RESTscape doesn't invent anything new (just adds some conventions, see later), so as you can expect a web command has a method and one or more arguments. Following with the previous example:

The method:
The arguments:
        fo-url =

Mono-argument web commands like this one are called filters or transformers and RESTscape defines some conventions for them (see later).

RESTscape rules/conventions

RESTscape adds several rules/conventions for the web command arguments:

  1. When an argument has a name that ends with "-url", it represents an URL and its value will be get after a web command call to that URL.
  2. If there is an argument named "back-url", the response will be a redirection to its value. To be a valid argument, the "back-url" value must point to a web command and MUST contain the following parameter: "${response-url}"
  3. For other arguments its value will be get from the call.
    1. If the call is a GET, the value will be URL decoded into a String or byte array.
    2. If the call is a POST, the value will be readed into a String, byte array, or byte stream.

To clarify these conventions, look at the following example:

In-line argument:

Off-line argument:

Uploaded argument (encoded as a multipart form):
                text = This is a text

Off-line argument with a back URL:

All of them are valid calls to the same service. A well behaved RESTscape service would be prepared to answer all of them and return the same result.

The reduced form of mono-argument web commands (filter pattern)

Those web commands that take only one argument (filters/transformers) can be reduced to a regular resource URI, as shown by the following example. This web command:

can be reduced to:

A well behaved RESTscape mono-argument web command would try to accept this call.

Web command chaining

Command nesting

The off-line call form provides the first form of web command chaining: nesting. As the argument is the result of evaluate a web command, and there's no limit to this, it's possible to nest web commands to any level.

Command nesting implies that in order to generate the final result, the web command tree will be processed from the leafs to the root. Cache techniques can be applied to not recalculate branches.

Command sequencing

The special "back-url" argument provides the second form of web command chaining: sequencing.

For command sequencing, a controller service will be the best solution. The controller handles de workflow among services, calling each participant services with a "back-url" pointing to the controller:

Call the form controller service:

The controller service inmediatly redirects to the first step (filling the form):

After filling the form, the controller service redirects to the second step (signing the form):
                ?file-url= <...temporal URL with the filled-webform...>

After signing the form, the controller service redirects to the third step (showing the final form in RTF):
                ?file-url= <...temporal URL with the signed-webform...>
Finally, the controller shows the final RTF to the user.

As you can see, very complexes services can be created by sequencing simple services. Scriptable controllers can be developed to chain all these services in very useful ways.