HTTP PATCH method. Content in the request body

Question

I'm developping a REST API using Symfony2. I have a reservation system and I would like to send an email to a customer when his reservation is validate by an admin.

I have a Reservation ressource, and we can validate a reservation using this url :

PATCH localhost/:id/validate

I want to know if is it correct to put the email content into the request body when validate a ressource, using the PATCH method.

If no, what should be the correct way ?

Thanks, Mehdi.

Answer 1

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 protected].
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 protected].
This reads as "make a validation for this reservation on email [email protected]". 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 protected]
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.