GET or POST to request receipt for an existing transaction via Email

Question

I was having a discussion with a colleague regarding the HTTP method of an API. The purpose of the API which looks like /booking/{bookingId}/receipt is to send the receipt of the booking to the registered email of the customer who completed the booking.

I argue that the method should be GET because the API caller is requesting for a resource, though through another mean and not the API response.

My friend argues that it should be POST as the API caller is posting a request for getting an email and is not getting anything in the API's response albeit a SUCCESS.

My question is what should be the correct HTTP method?

• Noel Frostpaw: What happens if I call the endpoint twice? Do 2 emails go out then? e.g, is the result always the same when calling the endpoint? If so, I'd go for GET, otherwise POST
• Abdullah Shoaib: @coding-bunny Yes the email will go out twice but a control will be in place so that the email is sent once in a while (let's say a day).
• Noel Frostpaw: Then I'd follow your coworker and go for POST, because your GET operation is not atomic, resulting in different behavior. Perhaps it would make more sense to let the sending be done by a different service, and have your current endpoint just be the data representation.
• Bart van Ingen Schenau: As a thought experiment: GET requests can be cached by intermediate servers. What would happen if you implement this API method using GET and then someone decides to put a caching proxy in front of it?
• Tersosauros: Why not change your question, and then ask yourself; "If I had an API to send emails would my /send_email/ endpoint be a GET or a POST?" Then the answer becomes a lot more obvious. Just because you access this reciept request via a HTTP API, doesn't mean you should ignore the Action the endpoint performs. Sending an email is not atomic or idempotent, or "safe".

Answer 1

RFC 7231, section 4.2.1 is relevant

Request methods are considered "safe" if their defined semantics are essentially read-only; i.e., the client does not request, and does not expect, any state change on the origin server as a result of applying a safe method to a target resource. Likewise, reasonable use of a safe method is not expected to cause any harm, loss of property, or unusual burden on the origin server.

This definition of safe methods does not prevent an implementation from including behavior that is potentially harmful, that is not entirely read-only, or that causes side effects while invoking a safe method. What is important, however, is that the client did not request that additional behavior and cannot be held accountable for it....

The purpose of distinguishing between safe and unsafe methods is to allow automated retrieval processes (spiders) and cache performance optimization (pre-fetching) to work without fear of causing harm. In addition, it allows a user agent to apply appropriate constraints on the automated use of unsafe methods when processing potentially untrusted content.

GET is semantically constrained to be safe, POST is not.

A key idea in understanding REST is the uniform interface; generic components (like a web browser) are permitted to act cleverly on the information presented to them. Using safe methods to trigger interesting side effects is a bad idea because the intermediate components are going to assume that those side effects, if any, are not significant (logging and such).