A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types).
When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions.
To some extent, people get REST wrong because I failed to include enough detail on media type design within my dissertation. That’s because I ran out of time, not because I thought it was any less important than the other aspects of REST. Likewise, I suspect a lot of people get it wrong because they read only the Wikipedia entry on the subject, which is not based on authoritative sources.
Translation: HTTP request methods (like PUT, POST, DELETE) mean nothing on their own. These verbs can only be defined in the context of a type of resource (like HTML). REST starts with media types and hypertext, not verbs. This is something a lot of people have gotten wrong.
This makes me wonder: Why does HTTP define specific verbs at all? Shouldn't verbs only be defined by a resource's content type? Why not just have HTTP define "request methods" with the concepts of safety, mutability, and idempotence and leave it at that?
I propose we eliminate specific verbs from the HTTP spec. Let's make content types like HTML define the request methods they need. We can achieve REST without common verbs.
PUTing this to the test
Let's see if the most popular media type out there, HTML, would be RESTful if HTTP didn't define specific request methods.
First: Roy says you can't have REST without hypertext. Does HTML define a media type with hypertext?
Yes. An HTML document can contain tags like <a href="..."> that link to other documents. If a client understands the HTML spec, then it can follow a chain of documents without implicitly knowing the structure of the information. The client can be dumb because the resources' capabilities are self-describing. This is what makes web crawlers and search engines possible.
Second: REST requires attention to how resources are accessed. Does HTML define how to access resources?
Yes. The HTML spec's processing model explicitly mentions the GET and POST verbs and how navigation works. Here are the important parts:
User agents can implement a variety of transfer protocols, but this specification mostly defines behavior in terms of HTTP.
The HTTP GET method is equivalent to the default retrieval action of the protocol. For example, RETR in FTP. Such actions are idempotent and safe, in HTTP terms.
In the case of non-idempotent methods (e.g. HTTP POST), the user agent should prompt the user to confirm the operation first, since otherwise transactions (e.g. purchases or database modifications) could be repeated.
The method and formmethod content attributes are enumerated attributes with the following keywords and states:
- The keyword get, mapping to the state GET, indicating the HTTP GET method.
- The keyword post, mapping to the state POST, indicating the HTTP POST method.
Success! HTML defines a media type with hypertext, and resources with state transfer characteristics. HTML would be RESTful even if HTTP didn't define specific verbs.
Conclusion
When I say, Let's remove verbs from HTTP 2.0, I mean it. This isn't incompatible with the goals of REST. We can have REST with fewer or no standard verbs in HTTP. The verbs can be specified by media types like HTML and their respective processing models.
As developers we can care about safety and idempotence without bloating the HTTP spec with uncommon verbs that don't translate between services (like LINK and SPACEJUMP). Our goal should be narrowing the protocol of HTTP to achieve Roy's goal of a simple architecture.