API ‘Initialize’ Method – Should It Be POST or GET?

apihttpmethodsrest

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:

  1. Check if user registered on the 3-rd party services.
  2. If it does not, register him on that services.
  3. 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:

  1. We can use it during the page initialization (POST can be used only once the page is loaded)
  2. We do not send any data for this method (except for user token in the headers)

Why POST

  1. 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:

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.

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 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

A request method is considered "idempotent" if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request

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

a safe request initiated by selecting an advertisement on the Web will often have the side effect of charging an advertising account.

From your description, it sounds to me like this could be a case where GET is an acceptable choice.

Agree with the idempotent analysis, but prefer PUT

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.

Frontend should not bother about any registration things, it just says us: "okay, I'm here, do whatever you need to get ready to work". Does this mean we should use GET then?

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

HTTP does not attempt to require the results of a GET to be safe.
What it does is require that the semantics of the operation be safe, and therefore it is a fault of the implementation, not the interface or the user of that interface, if anything happens as a result that causes loss of property (money, BTW, is considered property for the sake of this definition).

Related Topic