PUT API response codes - 200 always vs 201/200

[Bhooshan Mogal]

Hi Folks,

I'm proposing to change the response code for idempotent v3 PUT APIs as follows:

# 201 (Resource Created) - if the resource was successfully created

# 200 (OK) - if the resource already exists, and wasn't modified

Pros:

* More accurate, since it specifies if the resource was created or it already exists

Argument: We could do that even by using 200 always, and indicating in the response message if the resource was created or it already existed

Cons:

* We say that a PUT is idempotent, meaning that the request can be issued repeatedly without changing its outcome. Now consider the situation where a PUT fails with a timeout. The client will retry, and because it is idempotent, it will expect the same response as if it were the first attempt. But depending on what happened on the server side, the response will now be either a 201, or a 200. So the client needs to be prepared for both response codes. 

Argument: Even though this change would mean that the API response may not be idempotent (201 or 200), underlying, it is idempotent in the sense that repeated calls do not change the state (of the MDS in this case).

* It would be easier for clients if we returned 200 always in idempotent PUT APIs (whether or not the resource was newly created), especially since most developers are not even aware of the existence of 201, they simply expect a 200 for successful calls. 

We should ensure that all APIs are consistent in this aspect. Please share your thoughts about this, since we are actively developing v3 APIs for CDAP, and if we do decide to make this change, we should make it now.

Thanks,

Bhooshan

[Poorna Chandra]

It is best to keep all success as simple 200. It keeps APIs simple. Especially since I don't think there is a need to distinguish between "Resource Created" vs "OK" in this case.

Thanks,

Poorna.

--
You received this message because you are subscribed to the Google Groups "CDAP Developer" group.
To unsubscribe from this group and stop receiving emails from it, send an email to cdap-dev+u...@googlegroups.com.
To post to this group, send email to cdap...@googlegroups.com.
Visit this group at http://groups.google.com/group/cdap-dev.
To view this discussion on the web visit https://groups.google.com/d/msgid/cdap-dev/CAKZddromSm4ZZScqP21a8fpcQo99xprGU7iiuEHLawAnZd4nNw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[Andreas Neumann]

+1 on Poorna. 200 OK!

You received this message because you are subscribed to the Google Groups "CDAP User" group.
To unsubscribe from this group and stop receiving emails from it, send an email to cdap-user+...@googlegroups.com.

To post to this group, send email to cdap...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/cdap-user/CAJhv_HWVr7p_6M_rhLvhWb7Fvv4-hMnOpoJEH-FoAvQM1eG7zQ%40mail.gmail.com.

[Bhooshan Mogal]

Ok. I take back that proposal. I'm going back to 200 OK always. If anyone wants to get back to it with strong reasons, please do so soon. :)