...

If you enter ID 99 (which does not exist),  will GET .../customers/99, which returns an empty document. The form will be displayed with default values (as entered originally by the designer). When submitted, the resulting XML document will be PUT to .../customers/99. This PUT will create a new customer with ID 99 (the behaviour depends on the implementation on the server - in our example, the PUT creates the customer).

Example

This example The database connector is a good way to understand ' handling of document URIs and the powerful capabilities of composing multiple document resources into view resourcesworking example of a restful service. You can download the entire example including source code and forms by clicking here.

This example follows the principles of REST and uses the Restlet framework but you can use any framework or server-side model that you like. As mentioned earlier,  forms can be thought of as View Resources that compose one or more Entity Resources (documents). In this example we have entities Customer and List of Customers. Reproduced here are the methods that they support.

This is implemented in the two classes: com.frevvo.restlet.customer.CustomersResource and com.frevvo.restlet.customer.CustomerResource. These simply provide implementations of the above methods returning the desired representation of the resource for a GET, creating a new customer for a POST and updating an existing customer for a PUT. In general, the representation that is returned depends on content negotiation via the Accept headers.

Select Customer

There are three forms. The first one is the Select Customer form. This form allows you to search for a specific customer. It uses the first GET method from the table above, and populates a drop down with the list of customers returned according to the search criteria. This is done using a rule. Edit the form, click on the Rules tab and open the Get Customer List rule.

if (S.value.length > 0) { 
eval('x=' + http.get('http://<hostname>/customers/?pattern=' + S.value));
C.options = x.customers; 
ID.options = x.ids; 
} 

This rule populates the dropdown Customers based on the list of customers returned by the GET method that is invoked by the rule. When a rule invokes http.get(), it also sets the Accept header in the request to 'application/json'. This causes the implementation to provide the JSON representation of the customer list. In this example, we return two JSON arrays: an array of names and an array of IDs. These arrays are used to populate the two dropdowns in the example - the Customer Names dropdown and the hidden Customer IDs dropdown. Try typing a search string (e.g. A). This will return the list of customers whose names start with A. Select a customer from the list. The second rule in this form ensures that the hidden Customer ID field is in sync with the selected customer.

The Form action for this form is set to the URI template: http://<hostname>/frevvo/web/user/gallery/app/_73zHwep_EduZgK0BUzi1Ug/formtype/__AKE4PgqEdusGKt5_HoCDw?_method=POST&customer={ID}. As described in the Multi page forms section, when the user clicks submit, the URI template above will be resolved based on the selected customer ID and the browser will be redirected to the resulting URI, which is simply that of the next form with a query parameter (customer=02, for example). This form is described below.

Customer Information

This form is described in the Updating a document section above. It GETs the XML representation for a specific customer using the third method in the table above, initializes the form with that information and displays it to the user. When submitted, the updated customer information is automaticlly PUT to the same [resolved] URI using the fourth method in the table above.

Create Customer

This form is described in the Creating a new document section above. When instantiated, it does a POST to the Read URI using the second method in the table above. This causes the server to create a new customer and return the URI of that customer.  will automatically follow this URI, GET the representation of the customer and display the form (presumably with empty values). When the user enters all required fields and submits the form,  will automatically PUT the resulting XML document to the URI for the newly created customer thereby updating the customer.

In this manner, the combination of URI templates, read/write methods and form parameters provides a very powerful and flexible way to interact with the web.Download the v2.4 database connector which comes with source code. Refer to the db connector tutorial to see how this restful service is used.