Additional action on REST resource update

Question

I have a User entity that looks like the following:

class UserVM {
    id: number;
    name: string;
    email: string;
}

There is a REST API to work with the list of users, where we can get the list an update an individual user by ID:

GET /api/users
PUT /api/users/1 { name: ..., email: ... }

Now, I need to add a checkbox to the user editor form, which says "Send changes report". If it is checked, the updated user receives an email saying "Your profile has been updated".

This checkbox is definitely not related to the User model, and I am wondering how to properly represent it in the API. Here are the few options I considered:

1. Separate UserVM and EditUserVM, add a new flag to the latter and use it for PUT requests
2. Add a different non-rest method that just sends the email, call it from the client after update
3. Add a query parameter like PUT /api/user/1?send=1 { ... }

What is the best practice for such cases?

Answer 1

As you want to "partially" update information related to user, you can use PATCH method for this. This will be a REST approach.

Regarding second option: if you add a different method like "/sendtheemail", this will be a RPC approach.

Also this SO question can be usefull for you: Best practice for partial updates in a RESTful service