[FIXED] RESTful / Crud based approach to controlling an entity behavior that is typically implicit

Issue

I am modifying a CakePHP application to have an API available on it. My intention is to try to keep keep the endpoints as close to being RESTful / Crud oriented as possible. Although I have a use case that that I am unsure of.

I have the following requests for adding and editing tasks:

PUT       /tasks
PATCH     /tasks/:id

One of the behaviors of task entity in the system I am working on is that they send emails to the effected users associated with the task, when a save or edit is performed. This allows the various parties surrounding the task to be updated on the status of the particular task.

However the the one issue is that in some uncommon cases the end user will need to be able to toggle if they want an email to be sent on the front end.

What is the proper RESTful / Crud oriented approach to flag the task endpoints to not fire the email in the API request?

There is no record of the email in the application's database and it is nice to have to functionality tied into the task life cycle hooks and called implicitly. So I am not crazy about doing something like creating an /emailTask set of endpoints. It seems like an optional flag in the task request would be cleaner, but might not be maintainable if we begin to have similar needs for other behaviors associated with tasks.

Thanks in advance for the help!

Solution

PUT /tasks

If you're intending to use this for adding tasks, use POST instead. PUT /tasks implies that you are overwriting all tasks.

As for side-effects, this to me feels like a decent use-case for a custom HTTP header. Perhaps something like Suppress-Notifications: ?1 ?

Why ?1 as a value? This is going to be the future default for new HTTP headers that specify a boolean:

https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-header-structure-15#section-4.1.9

Answered By - Evert