I’m designing an API. And obviously first question I had was: what’s the real difference between PUT and POST? Someone is always wrong in the internet. And there are a lot of opinions out there. But I think the most simple and clear on comes from stackoverflow:
PUT implies putting a resource - completely replacing whatever is available at the given URL with a different thing. By definition, a PUT is idempotent. Do it as many times as you like, and the result is the same. x=5 is idempotent. You can PUT a resource whether it previously exists, or not (eg, to Create, or to Update)!
POST updates a resource, adds a subsidiary resource, or causes a change. A POST is not idempotent, in the way that x++ is not idempotent.
Easy.