CODEWITHSUNDEEP
restapi-design
mel-mouk
mel-mouk

Reputation: 98

Restful business logic on property update

I'm building a REST API and I'm trying to keep it as RESTful as possible, but some things are still not quite clear for me. I saw a lot of topic about similar question but all too centered about the "simple" problem of updating data, my issue is more about the business logic around that.

My main issue is with business logic triggered by partial update of a model. I see a lot of different opinion online about PATCH methods, creating new sub-ressources or adding action, but it often seems counter productive with the REST approach of keeping URI simple and structured.

I have some record that need to be proceeded ( refused, validated, partially validated ..etc ), each change trigger additional actions.

There is a few other change that can be made to the status but this is enough for the example.

What would be a RESTful way to do that ?

My first idea would be to create actions :

It seems RESTful to me but too complicated, and moreover, this approach means having multiple route performing essentially the same thing : Update one field in the record object

I also see the possibility of a PATCH method like :

But I feel it can start to be too complex when I will have the need to perform similar action for other property of the record.

My last option, and I think maybe the best but I'm not sure if it's RESTful, would be to use a sub-ressource status and to use PUT to update it :

No matter what the previous value was, switching to accepted will always trigger the creation, switching to refused will always trigger the email ...etc

Are those way of achieving that RESTful and which one make more sense ? Is there other alternative I didn't think about ?

Thanks

Upvotes: 1

Views: 758

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57257

What would be a RESTful way to do that ?

In HTTP, your "uniform interface" is that of a document store. Your Rest API is a facade, that takes messages with remote authoring semantics (PUT/POST/PATCH), and your implementation produces useful work as a side effect of its handling of those messages.

See Jim Webber 2011.

I have some record that need to be proceeded ( refused, validated, partially validated ..etc ), each change trigger additional actions.

So think about how we might do this on the web. We GET some resource, and what is returned is an html representation of the information of the record and a bunch of forms that describe actions we can do. So there's a refused form, and a validated form, and so on. The user chooses the correct form to use in the browser, fills in any supplementary information, and submits the form. The browser, using the HTML form processing rules, converts the form information into an HTTP request.

For unsafe operations, the form is configured to use POST, and the browsers therefore know that the form data should be part of the message-body of the request.

The target-uri of the request is just whatever was used as the form action -- which is to say, the representation of the form includes in it the information that describes where the form should be submitted.

As far as the browser and the user are concerned, the target-uri can be anything. So you could have separate resources to handle validate messages and refused messages and so on.

Caching is an important idea, both in REST and in HTTP; HTTP has specific rules baked into it for cache invalidation. Therefore, it is often the case that you will want to use a target-uri that identifies the document you want the client to reload if the command is successful.

So it might go something like this: we GET /record/123, and that gives us a bunch of information, and also some forms describing how we can change the record. So fill one out, submit it successfully, and now we expect the forms to be gone - or a new set of forms to be available. Therefore, it's the record document itself that we would expect to be reloading, and the target-uri of the forms should be /record/123.

(So the API implementation would be responsible for looking at the HTTP request, and figuring out the meaning of the message. They might all go to a single /record/:id POST handler, and that code looks through the message-body to figure out which internal function should do the work).

PUT/PATCH are the same sort of idea, except that instead of submitting forms, we send edited representations of the resource itself. We GET /record/123, change the status (for example, to Rejected), and then send a copy of our new representation of the record to the server for processing. It would therefore be the responsibility of the server to examine the differences between its representation of the resource and the new provided copy, and calculate from them any necessary side effects.

My last option, and I think maybe the best but I'm not sure if it's RESTful, would be to use a sub-resource status and to use PUT to update it

It's fine -- think of any web page you have ever seen where the source has a link to an image, or a link to java script. The result is two resources instead of one, with separate cache entries for each -- which is great, when you want fine grained control over the caching of the resources.

But there's a trade - you also need to fetch more resources. (Server-push mitigates some of this problem).

Making things easier on the server may make things harder on the client - you're really trying to find the design with the best balance.

Upvotes: 1

Related Questions