Support form creation

[gillarramendi]

We have been reviewing the state of the art regarding HATEOAS within Java environments such as Spring HATEOAS and JAX-RS and none of the implementations include any form (create/update) support, only link creation.

Taking into account that the most important hypermedia format (HTML) includes a great support for forms, offering a complete and self-contained description of the update/create options offered by a web app, we consider that it would be an interesting feature to add this support to Spring HATEOAS.
It means that clients will know which is the contract offered by the API update/create interactions, including the possible fields and if necessary the possible values for each property/field. In other words, the hypermedia format will guide the developer to implement form interactions with a self-contained format.

Of course, the first decision to add this support is to define the hypermedia format. There are already some hypermedia formats that support forms, like Hydra and Siren. We consider that the most natural option that fits with Spring HATEOAS, based on HAL, is HAL-FORM (https://github.com/mamund/hal-forms). Basically, an optional extension of HAL for forms support.

As an starting point, we created a first draft implementation including a form builder that allows the definition of the form fields and a *_MessageConverter *_that renders it in HAL-FORM format. In addition, we have proposed some updates within HAL-FORM specification, basically to determine the possible values for each field, and we are in conversations with Mike Amundsen @mamund, the specification author, to include them in the specification.

• Determine the possible values for a field mamund/hal-forms#9
• Multiple templates support mamund/hal-forms#10

We created an example application that shows the usage of the new API to create Forms (https://github.com/hdiv/hal-forms-sample).

For example, a form with two fields is created in this way:

ControllerFormBuilder formBuilder = ControllerFormBuilder
    .formTo(ControllerFormBuilder.methodOn(TaskController.class).create(new Task()));

formBuilder.property("description").readonly(false);
formBuilder.property("priority").suggest().values(new Priority[]{Priority.High, Priority.Low});
Form form = formBuilder.withDefaultKey();

resource.add(form);

And the generated HAL-FORMS response:

{
  "_links": {
    "self": {
      "href": "http://localhost:8080/tasks"
    }
  },
  "_templates": {
    "default": {
      "method": "POST",
      "properties": [
        {
          "name": "description",
          "readOnly": false
        },
        {
          "name": "priority",
          "suggest": {
            "values": [
                "HIGH",
                "MEDIUM",
                "LOW"
              ]
          }
        }
      ]
    }
  }
}

Any thoughts will be appreciated.
Thanks in advance.

@robertovelasco, @iunanua, @gillarramendi

[gregturn]

Superceded by #612 and resolved via 70448a8.

Final solution isn't precisely the same thing, but we plan to iterate over it in the near future and expand to support other mediatypes. Feel free to check the HAL-FORMS section of code and their corresponding unit tests.

Also, see monitor Spring HATEOAS Examples repo as we plan to add an Affordances example very soon.

[pivotal-issuemaster]

@gillarramendi Please sign the Contributor License Agreement!

Click here to manually synchronize the status of this Pull Request.

See the FAQ for frequently asked questions.

[pivotal-issuemaster]

@gillarramendi Please sign the Contributor License Agreement!

Click here to manually synchronize the status of this Pull Request.

See the FAQ for frequently asked questions.

[pivotal-issuemaster]

@gillarramendi Thank you for signing the Contributor License Agreement!