I've read the Fielding's thesis that defines the REST architectural style and noticed that the defined style appears to significantly conflicts with the so called "archetype controller", that a definition can be found in many places, like here.

The first thing to highlight here is that the "resources archetypes" is not present in the original thesis, it was a later addition (I don't know who made this), and that is OK. If it is not present in the beginning, I assume that the complement of this resource style is not part of the REST constraints.

But the issue here is that it seems to mismatch with what Fielding originally wrote about this:

Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.


The "archetype controller" seems to be a kind of a Remote Procedure Call. Not when he was talking about REST, but about HTTP, he also made the observation that HTTP is not RPC:

People often mistakenly refer to HTTP as a remote procedure call (RPC) [23] mechanism simply because it involves requests and responses. What distinguishes RPC from other forms of network-based application communication is the notion of invoking a procedure on the remote machine, wherein the protocol identifies the procedure and passes it a fixed set of parameters, and then waits for the answer to be supplied within a return message using the same interface.

What distinguishes HTTP from RPC isn't the syntax. It isn't even the different characteristics gained from using a stream as a parameter, though that helps to explain why existing RPC mechanisms were not usable for the Web. What makes HTTP significantly different from RPC is that the requests are directed to resources using a generic interface with standard semantics that can be interpreted by intermediaries almost as well as by the machines that originate services. The result is an application that allows for layers of transformation and indirection that are independent of the information origin, which is very useful for an Internet-scale, multi-organization, anarchically scalable information system. RPC mechanisms, in contrast, are defined in terms of language APIs, not network-based applications.


The question is, am I wrong, or has something wrong with the "archetype controller"?

  • 1
    Basically, what the industry calls REST(ful services) and what Fielding was talking about (a generalized architecture for heterogeneous internet-scale networks) have practically nothing to do with each other, except superficially. Sep 8, 2021 at 21:21
  • 1
    *for a distributed application running on a heterogeneous internet-scale network Sep 8, 2021 at 21:41

3 Answers 3


I'm trying to find the original source for REST Archetypes. A search suggests that it might have originated in the book REST API: Design Rulebook by Mark Massé (O'Reilly 2011) (Google books search). There are no useful search results before 2011.

I agree with your assessment that such controller/action-oriented endpoints typically conflict with Fielding's fundamental notions of REST: actions aren't resources with state. But your quoted section shows that RPC isn't in conflict with HTTP. REST is one style of using HTTP (and it harmonizes extremely well with the concepts underpinning HTTP), but it's also valid to use a more RPC-like style.

Regardless of whether we believe that the Controller Archetype is proper REST, it is useful as a description of the HTTP APIs people actually build. In industry, “REST” has become a catch-all term for all HTTP-based APIs that involve multiple endpoints (as opposed to a single endpoint used for SOAP or GraphQL operations).

  • +1 for tracing this to Mark Massé Sep 10, 2021 at 4:11

There is nothing wrong with "controller" style resources in general.

In your quote Fielding says so himself. He says (my interpretation obviously), RPC is not different because of syntax necessarily, but because it is not part of a generic interface (like HTTP with generic verbs), which is the only way intermediaries (proxies, caches, etc.) can work with stuff they don't really understand in depth. Which is in turn needed for large scale systems.

What many projects choose to ignore however, is that Fielding specifically says that any "API" not based on hypermedia (i.e. links and forms) can not be called "REST".

The title of your linked article "REST Resource Naming Guide" is in itself contradictory. There is no "naming" in "REST", at least none that clients should be interested in. Resources should be named based on whatever is convenient for the server, with the option to change at any time without notice.

The client must not know URIs on the server. They get that all dynamically, and should not care what they are. They could be all random gibberish as far as the client is concerned.


The first thing to highlight here is that the "resources archetypes" is not present in the original thesis, it was a later addition

That's not right - REST and "resources archetypes" are a completely different ideas.

REST, as you noted, is an architectural style. His thesis is, essentially, a message to other experts in the field of network protocol design, describing how to create an architecture that will support web scale applications like... the world wide web.

Now, Fielding doesn't use the language of "archetypes", but you will find that he references a few common types of resources: web pages, images, applets, and style sheets.

If you were to look in your browser history today, you're unlikely to find an applet, but web pages, and style sheets, and images are still common, as are scripts, audio, and video.

But also, as you read the thesis, notice what's missing. Fielding doesn't talk about spelling conventions for resource identifiers, or arranging resources hierarchically. Those design decisions are simply at the wrong scale - those decisions aren't architecturally significant.

Is the "archetype controller" really complies with REST architectural style

Ugh, the literature is such a mess.

A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs.

What I think you need to pay attention to here: how REST and SOAP differ. In so far as controllers resemble SOAP, they aren't "REST compliant".

Consider this example, copied from wikipedia:

POST /InStock HTTP/1.1
Host: www.example.org
Content-Type: application/soap+xml; charset=utf-8
Content-Length: 299
SOAPAction: "http://www.w3.org/2003/05/soap-envelope"

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:m="http://www.example.org">

Notice, in particular, that while the spellings used in the envelope imply that this request is "effectively read only", the HTTP metadata doesn't describe that semantic, which means that general purpose HTTP connectors can't tell what's going on.

In effect, we've reduced an application protocol to a mere transport protocol that conveniently goes through port 80.

That said, we do have web forms which include input controls for uploading a file, so that a browser can copy a picture from your machine and send it to a server that will send back a copy of the picture where all of the faces have clown noses. Is that REST? Most of the important elements are there, the only real difficulty is that HTTP doesn't currently have a method with these semantics, so we fall back to using POST, and again the connectors are kind of in the dark.

HTTP's one hammer for "effectively read only" is GET, and GET request-bodies have no defined semantics, which means packing information into the URI. That's fine when you are dealing with text input controls, but a request with multiple megabytes of image data encoded into the URI is going to trigger a 414 URI Too Long response as soon as it hits a connector with a sane security design, so something has to give.

If the working group manages to standardize the get-with-a-body proposal they are currently working on, we might have a better answer.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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