Can REST resources represent behaviour?

Question

In the red book by V. Vernon it says about REST:

In RESTful HTTP, the methods are the HTTP verbs - most importantly, GET, PUT, POST, DELETE - that can be applied to resources. Even though it might appear so at first sight, these methods do not translate to CRUD operations. It is very common to create resources that do not represent any persistent entity but instead encapsulate behaviour that is invoked once an appropriate verb is ued on them

I have read a few articles about REST and its implementation, and I have written code that consumes REST APIs, but to my knowledge, I have never seen the implementation of a resource as behaviour. First of all, I was under the impression that REST resources are represented as nouns, but one would expect behaviour to be represented by a verb.

Even in the APIs of multinational companies with millions of products in their databases, I encounter endpoints like /documents/create, which is not REST and also does not leverage the possibilites of having resources representing behaviour.

Am I missing something? And how would I go about designing an endpoint that represents behaviour, in order to do things beyond just simple CRUD?

Answer 1

REST as a concept relies on the HTTP Method to be your verb. I.e. you GET a resource, or change it by POST, PATCH, or PUT. For simple Create, Read, Update, Delete (CRUD) behavior this maps well. If you need to create a resource, the typical interactions follow:

• HTTP POST to /documents
• On successful create, respond with 201 Created and a Location header with the URL to the created resource
• Use the most appropriate response code for the type of error if the record cannot be created

There is another concept where you are not using REST, but more of a Remote Procedure Call (RPC) style of interaction. Your example of /documents/create is an RPC style API.

Impacts

Neither approach is inherently right or wrong. REST is very prescriptive as to the interactions, whereas RPC has some more leeway. Whatever your choice, I recommend you define the semantics of your API and make it consistent throughout.

There are other tools that can help make your API more useful:

• OpenAPI provides a manifest to make the API self-documenting
• Consistency is more important than the design approach you use. REST, HATEAOS, and other standards are efforts to prescribe the rules of making things consistent

Answer 2

I think you might be missing the whole REST-wars of the 2010s (or thereabouts). That was the time when the current interpretation (CRUD, Swagger/OpenAPI, etc.) of REST started to establish itself. Most notably against the apparent wishes of its creator.

This just means that the term "REST" lost its meaning to some extent. Debating what is, and isn't REST is therefore somewhat moot.

About your specific question: Have you ever logged in on the web? That endpoint that gets the POST with username and password is a behavior. When you use google, that page with the query input and submit button submits to a "RESTful" endpoint that is behavior. Actually most forms you submit on the web goes to a "RESTful" endpoint on the server with behavior.

As to the colloquial JSON-based "REST" endpoints, those should also work through forms actually. In the original REST concept by Roy Fielding, hypertext was one of the requirements of the whole thing. Which meant that we needed to tell the clients where, how and what to submit with links and forms, just like in HTML.

Since all endpoints should work like that, most would therefore be behavior, not data. Of course, barely anybody does that, so I can not be sure if that is what V. Vernon talks about.

Answer 3

Am I missing something?

A little bit, maybe.

REST is the architectural style of the world wide web; it a collection of constraints that were used in the 1990s to aid the development of the HTTP/1.1 standards (RFC 2068, RFC 2616).

So when we are talking about resources, "information that can be named", you can think of resources as generalizations of documents. See Webber 2011 - we use HTTP to transfer documents over a network.

So we have GET semantics to retrieve a document, and PUT, POST, PATCH semantics to modify documents.

The interesting business behaviors are side effects of the edits we make to documents. But from the outside, a REST API is just a dumb document store.

---

A resource identifier like /documents/create doesn't necessarily violate REST principles.

Consider how we send information to a server on the web: that usually happens by navigating to some document that has a web form, we input our information into the form, and when we submit the form our browsers uses standardized form processing rules to create from the form an HTTP request.

That's REST, and it doesn't stop being REST because the form URI has a "that's not REST" spelling, and it doesn't stop being REST if the form.action has the "that's not REST" spelling.

Because REST cares about caching, and because HTTP caches have standardized mechanics, choosing a resource model that is well aligned with caching is going to allow you to leverage all of the general purpose work that has been done on web caches "for free".

---

It is very common to create resources that do not represent any persistent entity but instead encapsulate behaviour that is invoked once an appropriate verb is used on them

Consider a request like this:

PUT /e2b1dbbc-1cdb-4510-a75e-b88284392d2c
Content-Type: text/plain

Please turn off the lights

From the perspective of REST components, this just says to change the current representation of the document /e2b1dbbc-1cdb-4510-a75e-b88284392d2c to match the body of the request.

Actually doing the work to turn off the lights is a side effect.

In other words, we could design our resource model such that each change is communicated by adding another document to our document store.

And that's fine.

Or we could instead design our resource model such that each change is communicated by modifying an existing document

POST /things-to-do
Content-Type: text/plain

Please turn off the lights

The document store model being a facade in front of our domain model, so that we can use all of the lovely tooling that has been developed for the web to talk to our domain.