REST action as part of request body - action not stored alongside entity

Question

I am working on an API that allows a client document to updated under the endpoint of PUT /client/{documentId}. As part of this document, I need to include an extra field 'ReplicateInManager' that notifies the server as to if the document needs to replicated in an external system, alongside the database for this API.

I am wondering if I am adhering to REST guidelines, as the 'ReplicateInManager' field will not be stored as part of the entity in the database. The server will read the field and if its value is true, raise actions asynchronously in other microservices, and effectively throw away the field.

My understanding is the best way to represent actions in a RESTful manner is to model the action as part of the entity, such as in this answer: https://softwareengineering.stackexchange.com/a/261647/364929

I believe in modeling the action as part of the request. However, I'm not sure if it's acceptable to then not store this field in the database entity.

Answer 1

You're fine, don't worry about it. :) As far as REST "guidelines", REST only defines that there should be standard methods of access, so intermediaries can tell what happens. For caching and other purposes.

The standard method for HTTP PUT has therefore the definition of what should happen in your case. That explicitly states:

[..] HTTP does not define exactly how a PUT method affects the state of an origin server [..]

And also

It does not define how resource state is "stored", nor how such storage might change as a result of a change in resource state, nor how the origin server translates resource state into representations.

So you're pretty must in the clear on that one. As long as you fulfill all the other requirements of a PUT, you're ok.

Answer 2

To me, it depends on the purpose of your model. I feel like you are breaking a paradigm, if you are putting postal information inside an envelope, on the letter you're trying to mail. However, if you have a structure whose purposes are to transfer the data, such as a box that you send your envelopes in, that a courier will open and re-examine, then it's fair game. This could could be why your domain object would differ from your DTO, or why you employ a messaging system instead of programming transport into your application layer. Think sub/pub, MQ, Message Broker, your (smaller, microservice-even) programs can then be more independent in function. Not all design must be within your application, it's a system - take advantage of that.

I'm new to this community, hope my answer is insightful and I invite alternate viewpoints.

Answer 3

In addition to @RobertBräutigam, when you are working on RESTful Web services, what really matters is sticking to the semantics of the HTTP.

The "model" we POST or PUT is not required to match 1:1 with the model we GET. We do it for convenience most of the time but it's not mandatory. If we had different models for each operation, it would be still REST, because REST is not only about how we shape data structures or URIs, it's rather about how we leverage architectural features of the WWW and to do so, we should adhere to the HTTP semantics as much as possible.

If you read RFC 9110 HTTP Semantics chapters 6.4.1 Content semantics or 9.3 Methods definitions you won't find any mention of semantics or rules involving representational models matching among methods. Again, we do that for convenience and overall we do it for consistency. Remember that consistency is a SHOULD have of any development or architecture.

as the 'ReplicateInManager' field will not be stored as part of the entity in the database

Doesn't matter

that notifies the server as to if the document needs to replicate in an external system, alongside the database for this API.

This is important. You have to guess if PUT semantics are aligned with this operation. For example PUT is meant to be idempotent and so should be ReplicateInManager when it's executed several times in a row or you might end up with multiple copies of document on the remote storage. Or even worse, causing an error totally unrelated to the operation PUT.