Introduction

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:

http://www.some-comp.com/products/product-523.pdf

This URL is pointing to a file served by www.some-comp.com... 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):

http://services.some-comp.com/fo2pdf?fo-url=http://www.mycom.com/products/product-523.fo

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:
        http://services.some-comp.com/fo2pdf
        
The arguments:
        fo-url = http://www.mycom.com/products/product-523.fo

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:
        http://services.some-comp.com/countWords?text=This%20is%20a%20text

Off-line argument:
        http://services.some-comp.com/countWords?text-url=http://www.some-comp.com/test/test.txt

Uploaded argument (encoded as a multipart form):
        http://services.some-comp.com/countWords
                
                text = This is a text

Off-line argument with a back URL:
        http://services.some-comp.com/countWords
                ?text-url=http://www.some-comp.com/test/test.txt
                &back-url=htpp://services.some-comp.com/count2html?count-url=${response-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:

http://services.restscape.org/fo2pdf?fo-url=http://www.mycom.com/products/product-523.fo

can be reduced to:

http://services.restscape.org/fo2pdf/http/www.mycom.com/products/product-523.fo

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

Web command chaining

Call the form controller service:
        http://services.some-comp.com/form-controller
                ?form-url=http://www.some-comp.com/forms/form523.xml

The controller service inmediatly redirects to the first step (filling the form):
        http://services.some-comp.com/webform/fill
                ?form-url=http://www.some-comp.com/forms/form523-webform.html
                &back-url=htpp://services.some-comp.com/form-controller?filled-webform-url=${response-url}

After filling the form, the controller service redirects to the second step (signing the form):
        http://services.some-comp.com/file/sign
                ?file-url= <...temporal URL with the filled-webform...>
                &back-url=htpp://services.some-comp.com/form-controller?signed-webform-url=${response-url}

After signing the form, the controller service redirects to the third step (showing the final form in RTF):
        http://services.some-comp.com/rtf/fill
                ?file-url= <...temporal URL with the signed-webform...>
                &back-url=htpp://services.some-comp.com/form-controller?final-rtf-url=${response-url}
                
Finally, the controller shows the final RTF to the user.