Form Profile

Profile: <http://level3.rest/profiles/form>

A Form is a hypermedia control that provides a form for the client to fill in and then accepts that form back in a POST request. Anyone who has ever filled out and submitted a paper form in the real world already knows how the Form profile works. The basic concept with Form is to GET the representation, fill it in, and POST it back.

HTML has had <form> controls since the beginning, and they have proven useful for capturing information and state from users in many applications. Over time, HTML forms have added valuable capabilities for client-side field validation and semantic field presentations like “password” and “email.” In a similar spirit, Level 3 forms can supply client-oriented schemas to assist the client in creating user presentations and valid form payloads.

Forms often create new resources, but can also be used to direct a client to a pre-existing resource that matches the submitted form’s content. A Form resource can also represent an API command that changes the system state.

Form Content

Forms in Level 3 supply their form representation in two ways. One is to deliver a simple object template with fields that are either empty or prepopulated. The other is to supply a form schema that the client uses to construct a form payload to submit. The client can learn the form representation during Discovery by reviewing the Content-Type header.

Discovery

The Form profile presents the required Profile and Allow headers as well as a Content-Type indicating the type of the request payload. The resource may provide a Content-Type like application/schema+json, application/prs.hal-forms+json or application/xml-dtd that can be used to construct a form payload. The client must understand the content type and how to use the schema to produce a submission payload.

Alternately the Form can send a template object with empty fields, which is a sufficient approach for simple forms. In this case the Content-Type will reflect the format of the template object, like application/json or application/xml.

Form Submission

First, a client GETs the representation from the Form resource. The representation could be a schema definition or a template object with empty fields. Both the schema and form template can include default values.

If the representation is a schema, then it should be used to construct a form object. If the representation is a template object, then it should be filled in by the client. The completed object is then POSTed back to the Form resource.

Clients should always GET the representation for every request rather than reusing the schema or form template from a previous request. The Form’s data requirements may have changed since the client last fetched the representation.

Once the client submits the form, the resource responds with a success message and a Location header pointing to a relevant resource. If the submission was unacceptable, then the resource responds with a client error status code and error messages indicating the problem. Common problems include missing required fields or incorrect data in the fields.

Rejections
Status Code Explanation
400 Bad Request The forms’s syntax is malformed.
409 Conflict Values in the data are not accepted by business validation rules.
422 Unprocessable Entity The form is semantically-incorrect.

Mixins

Representation Mixin

A Form resource can provide the Representation profile as a mixin so the client can receive the relevant Location’s representation in the submission response.

Entity Mixin

A Form can provide the Entity profile as a mixin so the client can benefit from cached Form requests as well as a stable submission schema via the Conditional Operation flow. If the Form’s schema and requirements have not changed, the client receives a 304 Not Modified status code.

Specifications

HTTP Extensions for WebDAV: RFC 4918

HTML 5.2: Forms

HTTP/1.1 Semantics and Content: RFC 7231


Copyright © 2019 Matt Bishop
Creative Commons Licence
This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.