First, about the resources and REST.
When you say PATCH localhost/:id/validate
you should read that as "I am updating an existing validate". "A Validate" is nothing, not even proper English. A validate is not a Resource, it is an action. When you have actions (verbs) in your URL, your API is RPC, not REST. Also see my longer answer here.
So, consider what you are really doing. One of below:
- You are updating a reservation
- You are creating a validation on a reservation
- You are replacing a reservation with a validated version of that reservation.
The first would make most sense and is simplest.
PATCH /reservations/{id} status=valid
Does the reservation already hold an email-adddress? Then use that. Otherwise consider sending an email along.
PATCH /reservations/{id} status=valid&email=foo@example.com
.
This reads as "update the reservation email and status with the following values".
Since PATCH (and POST) may have side-effects, sending out a mail is perfectly fine.
The second is neccessary when one reservation has many validations. Or when the REST-clients need to track validations separately from reservations (e.g. a GET /reservations/{id}/validations/{id}
). In those cases it makes sense to have a Validation
resource.
POST /reservations/{id}/validations
.
If the reservation has no email-address, send it along.
POST /reservations/{id}/validations email=foo@example.com
.
This reads as "make a validation for this reservation on email foo@example.com".
This reads as "I make a new validation on this reservation". Since POST (and PATCH) may have side-effects, sending out a mail is perfectly fine.
The third case is important, because of side-effects. If you want to present a way where clients can be certain there are no side-effects, this comes into play.
PUT /reservations/{id} room=12&date=1970-01-01&status=valid&email=foo@example.com
This reads as "replace the exsiting reservation with a validation that has a validated status." Since PUT should never have side-effects, a client can be certain that replaying this (on e.g. network errors, heavy load or whatever) will never cause the user to be spammed.