2

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?

3 Answers 3

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
1
  • My question was about whether resources would have to represent entities, like document, or whether they could represent behaviour, as mentioned in the book. I changed the title to make it more clear.
    – Hans
    Jun 17, 2021 at 13:29
1

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.

2
  • Okay so we live in a world of CRUD, and for a second there I thought we might actually use REST to do more elaborate stuff, which the quote seems to suggest is possible. I don't really understand what you say about endpoints (=resources) being behaviour in all these cases. If they all were behaviour, why would people still be complaining that REST limits them to a set of 4 verbs to implement the behaviour of their apps.
    – Hans
    Jun 17, 2021 at 14:01
  • If you're building a RESTful HTTP application, you are limited to using the existing HTTP verbs. But, a well written client shouldn't even know about that. It should only know about specific Media Types and how to process those. Then again, I'm talking about how it should work, not how most projects do it. I mean, Stackoverflow is a HTML-based RESTful App, using only 2 verbs, GET and POST. Did that bother anybody? Was that really a limitation? Jun 17, 2021 at 14:46
1

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.

1
  • Thanks for the link to Webber's talk. Regarding the side effects, your example seems to work well in theory, but I don't really see how I could apply this to the growing complexity of an application. POSTing a document will have side effect A, PUTting a document will have side effect B, what if I have many different side effects (business rules) that need to happen in different use cases with the same resource?
    – Hans
    Jun 20, 2021 at 10:34

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.