Support for automatic creation of forms

[dschulten]

As a service implementer, I want to use existing information about a controller method to create a forms-like response which points to the controller method, so that my clients need no out-of-band information in order to build a suitable request.

As long as a server can give expanded links to the client like example.org/persons/12345, it is easy to avoid out-of-band information.

However, if the server needs input from the client, expanded links are not enough. The server can respond with non-expanded URI templates [0] where the client must fill out the placeholders, as in example.org/persons/{personId}. But there is no standard media type to return such templates yet, and the client must be programmed to expand them. There are implementations for this [1], but when it comes to required request bodies for a POST or a PUT, a URI template is not enough anyway.

If the server expects GET request parameters with defaults for some parameters, or restrictions for valid parameters, or if it needs to tell the client that a POST to /persons is needed and how the POST body should look like, a media type is needed which allows to give this information to the client.

Currently only few media types are capable of this. Examples:

• text/html (Jon Moore's Oredev talk)
• application/vnd.siren+json [2]

The Spring MVC controller methods contain all necessary information how a form should look like. Leveraging the new methodOn() idiom for controller methods, it is possible to create a form like this [3]:

@RequestMapping(value = "/customer", method = RequestMethod.GET)
public HttpEntity<FormDescriptor> searchPersonForm() {
    FormDescriptor form = ControllerFormBuilder.createForm("searchPerson",
        methodOn(PersonController.class).showPerson(1L));
    return new HttpEntity<FormDescriptor>(form);
}

The server can be configured to render the Response as an html form using an HtmlFormMessageConverter[4] if the client accepts text/html, and we could create other converters for siren etc. I think for now it would be perfectly OK to respond with html forms for complicated requests and with json/hal/collection+json if we only need expanded links.

The advantages are:

• The client does not need to learn out-of-band how to construct a request for a POST or parameterized GET, there is a standard for this. We only need a client framework which is able to handle a standard media type such as an html form, or other emerging standards like siren which define a possible action for the client. Spring-hateoas could easily offer such a client framework [5]
• The server can evolve quite independently from the client, e.g. by adding default values for new request parameters which old clients can submit as-is
• Developers can "browse the API" to find out which requests the client must use and program the client against rels, form names and field names which come with the response.

Prepared pull request #38 with tests, strictly focused on html form support ;-)

Feedback welcome.

[0] http://tools.ietf.org/html/rfc6570
[1] https://github.com/damnhandy/Handy-URI-Templates
[2] https://github.com/kevinswiber/siren
[3] https://github.com/dschulten/spring-hateoas/blob/master/src/main/java/org/springframework/hateoas/HtmlFormMessageConverter.java
[4] https://github.com/dschulten/spring-hateoas-rest-service-sample/blob/master/rest-service/src/main/java/de/escalon/rest/PersonController.java
[5] https://github.com/dschulten/spring-hateoas-rest-service-sample/tree/master/spring-hateoas-client

[dschulten]

superseded by #71