I'm designing a web-app that will use a REST API. What I've never understood is what is REST's equivalent of HTML forms? HTML5 forms have a reasonably rich set of server-provided, declarative controls, constraints and validation.

Is the server supposed to send a MIME type (name) or is there an equivalent of HTML forms for REST? A named type (MIME or otherwise) is inferior to an HTML form as it is only a name, not the actual form construct; the client would need to interpret the name into a form - which is incorrect IMO - too much knowledge in the client.

My client would take the form definition and create an HTML form equivalent.

XForms (https://en.wikipedia.org/wiki/XForms) always struck me as "nice" but it's XML based and seems pretty dead. I'm not averse to XForms as I have a preference for XML, XSD, XSLT, XPath over JSON but I'll probably go with the flow and use JSON for simplicity.


  • 1
    You want a REST API that returns something that will ultimately be used to generate a HTML form? Why not return a HTML form in the first place? Oct 26 at 11:18
  • Yes, I think you're right; I shall just stick to dynamic HTML with a little JS for flavour.
    – David Kerr
    Oct 26 at 14:39

HTML forms and REST services are typically glued together on the client by a frontend framework like React or Angular. The main benefit of REST services is reusability across devices and applications, not any magical framework that transforms JSON or XML into an HTML form.

If including a large JavaScript framework is not desirable, then consider creating a middle tier web application that sits between the client and your REST services. This web application would aggregate all REST calls necessary to build an entire web page, or partial web page and return HTML to the client. This would allow you to leverage popular server side frameworks, many of which use a form of Model-View-Controller (MVC) architecture.

  • Thanks for helping me clarify my thoughts. My system is simple and only depends upon my 1 web service, currently implemented as dynamic HTML to a Postgres backend, with some very simple and optional JS to enhance it progressively. I'm about to reimplement the UI and wanted to take the opportunity to improve the architecture. I think I shall just leave it as is; a REST API doesn't add enough value given my really tight time constraints.
    – David Kerr
    Oct 26 at 14:38

What I've never understood is what is REST's equivalent of HTML forms?

REST's equivalent to HTML forms is... HTML forms. Which is to say, "hypermedia as the engine of application state" is a REST architectural constraint, so we would always expect there to be some general purpose mechanism for describing forms.

REST APIs must be hypertext driven -- Fielding, 2008

One place where modern APIs fall down is that application/json is a data interchange format, not a hypermedia format. So even though we throw around terms like "RESTful" to describe such an API, that decription isn't particularly accurate.

For API that use edits of JSON documents to trigger business activity, you can lean into PUT (because the payload is going to be an edited copy of the representation), and you can use PATCH (using metadata provided by the server to know which patch document formats are supported).

But if you want links and forms, then you need media types that include them in the schema. If you want POST, then you need some way to describe to a general purpose client the media type and schema of the payload.

HAL-FORMS is an example of a general purpose media type designed to meet this need.

In practice: nobody in the "RESTful" world cares about "general purpose". Instead, there attention is on describing how to create a specialized client that understands how to talk to their servers.

The "browser", as a general purpose connector that integrates with the document transfer application on behalf of the intelligent client is absent. Consequently, "forms" have very little benefit, because there's no general purpose connector to take advantage of them. Instead, we use "out-of-band" communication channels to describe what the body of a POST request should look like.

  • Thank you. I think I shall just stick with dynamic HTML with a little optional JS to give it some flair, and not implement a REST API. It's currently working well enough with zero external frameworks or libraries (old skool). I've been tying myself up in knots looking for a framework to meet my requirements but I would be over engineering it at this stage.
    – David Kerr
    Oct 26 at 14:38
  • Sounds good to me. You might want to review this API - medium.com/i-dont-know-what-i-m-doing/… Oct 26 at 14:49
  • That's funny. My app is functional (not pretty) without JS. Amongst other "whizzy" things, the JS simply enhances the links to fetch the destination page, strips all the page stuff and sets the content in a multi-column layout (data is hierarchical). I might add some kind of partial parameter to the URL to minimise excess verbiage, but then I don't want JS firkling with the URLs.
    – David Kerr
    Oct 26 at 16:19

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.