Pages and Forms are First-Class Abstractions…not REST
Accepted
CreatedContext
A website is made almost entirely of web pages. Those pages typically allow interaction with the server via forms. Although fetch and non-browser clients exist and are important, the primary client of a website is a Web Browser.
Concerns or Issues
Designing a web app around a REST-like set of HTTP verbs and resources requires creating an abstraction that isn't necessarily real and not usually that helpful. Developers often find themselves wanting to create RPC-style routes via HTTP POST so that the interactions between browsers and the web app are more clearly aligned with reality. There is little benefit to allowing a form to POST to a server with a special _method parameter to pretend that an HTTP PUT has been submitted instead.
While PUT, PATCH, and DELETE can be useful in API scenarios, for most websites, the browser will GET any page and POST form data back.
Decision
Brut will provide an API that encourages the creation of pages and forms. Brut will allow the developer to explicitly declare what web pages their website has and what forms their website can receive. While Brut will allow any HTTP METHOD to be received, the primary way in which a developer will design their routes will be pages and forms.
Options Considered, but Not Chosen
Many web frameworks use a resource
based system where the developer declares a resource and then which of the five common verbs are supported. Additionally, they may declare that a resource can provide an index and an individual endpoint. This is rejected as both overcomplex and oversimplistic. Developers must jump through conceptual hoops to fit their use-cases into a single resource with five operations.
System Qualities or Desired Consequences
The hope is that the features and use cases of the app can be more directly reflected in the urls, pages, and forms being used. Further, the app in the browser can be more clearly connected to code since a browser shows a page, which maps to a page in the web app. The browser submits a form, which is defined in the web app.
Downsides
A benefit for the resourceful/restful approach is that the layer of route definition has a sheen of consistency and compactness. The approach Brut takes means that the route definitions are a longer list of potential inconsistent urls. For example, a routes could be /widget/:id or /organizations/:id. This consistency will be something the app developer must manage.
Additional Rationale
Brut will provide additional abstractions for managing parts of a page, managing form submission, and implementing HTTP APIs. These need not distraction from the core mission of a website to serve pages and process forms.