0

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.

Mehdi Chamouma
  • 67
  • 1
  • 8
  • The other day i was using swagger for api documentation and for the first time i came against the PATCH request, i wasn't aware of this type of request before. I then searched for it and found this http://pic.dhe.ibm.com/infocenter/tivihelp/v58r1/index.jsp?topic=%2Fcom.ibm.mif.doc%2Fgp_intfrmwk%2Foslc%2Fc_oslc_patch_method.html if anyone can explain better it is much appreciated. Thanks – Syed Raza Mehdi Sep 22 '14 at 05:00

2 Answers2

9

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.

berkes
  • 25,081
  • 21
  • 107
  • 188
  • Perfect answer. Thanks – Mehdi Chamouma Jun 29 '17 at 12:14
  • I guess the sentence after the PUT should read as follows: 'This reads as "replace the exsiting reservation with a reservation that has a validated status." ' or: 'This reads as "replace the exsiting reservation with another one that has a validated status." ' – user1708042 Feb 12 '21 at 15:07
1

If the goal is to validate, wouldn't POST be more appropriate? The notion of validating is more RPC-like than resource-like. According to RFC 5789, PATCH should be used to partially modify a resource.

NathanAldenSr
  • 7,474
  • 3
  • 35
  • 50
  • When validating, the ressource goes from "unvalidate" state to "validate" state. That why I thought that the ressource is partially modified. I didn't create any new ressource when I do that, so why use the post method ? – Mehdi Chamouma Mar 24 '14 at 18:25
  • `POST` is generally used with RPC-style web services. You may be modifying the resource, but the URL looks like a RPC. That's the only reason I suggested `POST`. Perhaps you should use `PATCH` on the resource URL itself and simply omit the `/validate`. Then, use the message in the content body to figure out *how* to patch the resource. – NathanAldenSr Mar 24 '14 at 18:28
  • @MehdiChamouma " That why I thought that the ressource is partially modified" is proper reasoning. You are correct that POST is not proper here, and PATCH more appropriate. – berkes Jun 15 '17 at 14:11