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
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.
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
The Form profile presents the required
Allow headers as well as a
Content-Type indicating the type of the request payload. The resource may provide a
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
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.
| ||The forms’ body is malformed.|
| ||The form is semantically-incorrect.|
| ||Values in the data are not accepted by business validation rules.|
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.
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.
HTTP Extensions for WebDAV: RFC 4918
- 422 Unprocessable Entity: section 11.2
HTML 5.2: Forms
HTTP/1.1 Semantics and Content: RFC 7231
- Content-Type: section 188.8.131.52
- 200 OK: section 6.3.1
- 201 Created: section 6.3.2
- 204 No Content: section 6.3.5
- 400 Bad Request: section 6.5.1
- 403 Forbidden: section 6.5.3
- Location: section 7.1.2
Copyright © 2019 Matt Bishop
This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.