Form Profile
profile: <https://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 pre-populated. The other is to provide a form schema that the client uses to construct a form payload to submit. The client can learn the form representation format 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 header indicating the request payload type. 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 good approach for simple forms. In this case the content-type will reflect the template object’s format, 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 the client uses it 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 form 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 form body is malformed. |
403 Forbidden | Values in the data are not accepted by business validation rules. |
415 Unsupported Media Type | The media type in the request is not supported. |
422 Unprocessable Entity | The form body is semantically-incorrect. |
Idempotent Submissions
A Form resource may offer Clients the option to submit an idempotency-key header to uniquely identify a submission request. The client can resubmit the request with the same header value to verify that their submission was accepted. Subsequent form submissions with the same idempotency-key and form body can be considered as ignored by the form resource.
If the resource offers this capability, the GET / HEAD response will contain an idempotency-key with either optional or required. optional means the client can supply a key if they choose, while required means they must submit an idempotency-key header.
When the client submits a duplicate request using the same idempotency-key, the resource will return the same response as the original request. If the request has different data than a previous request using the same idempotency-key, the resource may choose to respond with a 422 Unprocessable Entity to indicate the forms are not identical.
The key format is described in the IETF Draft document for idempotency-key. Like etag, wrap the value in double quotes; for example: idempotency-key: "a7a6dbe0".
idempotency-key Rejections
| Status Code | Explanation |
|---|---|
400 Bad Request | idempotency-key header required, but the client did not send one. |
409 Conflict | The resource is still processing a previous submission with the same key. The client should try again later. |
422 Unprocessable Entity | The form body does not match the original submission body sent with this idempotency-key. |
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.
Specifications
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 3.1.1.5- 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
- 415 Unsupported Media Type: section 6.5.13
location: section 7.1.2
The idempotency-key HTTP Header Field: section 2
© 2019-2023 Matt Bishop
This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.