We faced an issue with an API "init" method, and trying to understand if we must use GET or POST http method in context of REST.
Preconditions: SPA on the frontend which communicates with our backend using REST API. SPA is meant to work with a 3-rd party service through our API.
Description: When user loads the SPA, frontend calls API method "init". This method does the following:
- Check if user registered on the 3-rd party services.
- If it does not, register him on that services.
- Always return "successful" response (except for internal server errors or problems during the communication with the 3-rd party service).
The question is: can we use GET method for this "init" or should we use POST instead.
These are pros and cons:
Why GET:
- We can use it during the page initialization (POST can be used only once the page is loaded)
- We do not send any data for this method (except for user token in the headers)
Why POST
- It seems like we should use post in such cases, because it provides some basic initialization, checks if everything's alright, and does not return anything, until some internal error is happened.
So we can't decide, in context of REST specification, what is the correct http method for this API call: GET or POST? GET looks more convenient, but we're not sure it's okay to use GET for this API method according to the REST ideology.
Best Answer
Key to the question of using GET is whether the semantics of the operation are safe:
In short: if you are using GET, you are telling clients and intermediary components that they can request the resource any time they like, even if the end consumer hasn't asked for it.
By definition, safe methods are necessarily also idempotent
Meaning, for example, if the client sends a GET request, and doesn't get a response, they expect to be able to send the request again, and repeat it as many times as necessary until an answer arrives.
If those semantics aren't acceptable, then you probably shouldn't be using GET.
RFC 7231 does offer an example of a case where the "safe" semantic is appropriate even though there are significant side effects when handling the request
From your description, it sounds to me like this could be a case where
GET
is an acceptable choice.Certainly "register me if not registered" is an idempotent action. It's not clear to me from the description whether that's an intended part of the protocol, or if it is really an implementation detail.
But the semantics of PUT are more than just "idempotent"; in particular, they imply that the client understands an appropriate representation of the resource. It's not clear from the original description whether the client is expected to be familiar with the details of registration, or if that's an implementation detail of the client.
Furthermore, the most common media type for hypermedia representations is still HTML, and HTML forms don't support PUT. So you either need to augment your representation with code on demand, or you need to replace your representations with some other media type that supports PUT actions.
Of course, many API discard the hypermedia constraint; which makes the PUT method more palatable.
I suspect that is the case: your description reminds me a lot of a read-through cache; with the client asking "give me the current representation", and the server worrying about the details (do we have a current representation? do we need to revalidate it?). A lot of the power of REST comes from its caching semantics.
It may help to review this remark from Roy Fielding in 2002