I promised myself to never-ever answer the "CRUD vs HTTP verbs" topic. I could not resist.
It is a huge shortcut to map CRUD operations to HTTP verbs POST, GET, PUT, DELETE. By the way, the definition of HTTP verbs defined in the HTTP RFCs (from RFC 1945 to RFC 7231) and the original thesis from Roy Fielding about REST (which is defining REST principles as an architectural style) never talk about one-to-one relationship between CRUD and PUT-GET-POST-DELETE.
While I understand that it might be confusing without deep-diving in long-long-lectures, the last RFC explains clearly what is the purpose of each HTTP verb including the difference between PUT and POST:
The fundamental difference between the POST and PUT methods is
highlighted by the different intent for the enclosed representation.
The target resource in a POST request is intended to handle the
enclosed representation according to the resource's own semantics,
whereas the enclosed representation in a PUT request is defined as
replacing the state of the target resource. Hence, the intent of PUT
is idempotent and visible to intermediaries, even though the exact
effect is only known by the origin server.
Therefore it would be perfectly valid to "create" a resource with both PUT and POST methods as well as "update" another one with, also, PUT and POST. It is actually even clearly stated with a few examples in the RFC. For instance in POST definition:
Appending data to a resource's existing representation(s).
I used to defined PUT and POST requests according their characteristics: the first one is idempotent, the second is not ... but could be.
Therefore, in my understanding, it is perfectly valid to perform an "upsert" (insert or update) to a resource which doesn't exist yet but for which you already know the URL, it is indeed idempotent. For instance:
PUT /resources/xyz
A last piece of evidence is the first line of PUT section in RFC 7231:
The PUT method requests that the state of the target resource be
created or replaced with the state defined by the representation
enclosed in the request message payload.
I hope it helps to clarify a little bit the topic.
Do you have any references to documented, truly REST APIs? In your experience, what (pragmatic) shortcuts were needed to veer from (some definition of) "pure" REST?
IMO Stripe API[^1] is following well the REST principles and constraints. Btw, if I well remember, they are not using PUT at all while they obviously allow users to update some resources.
They implemented an "Idempotency-Key" header that you could maybe call a "shortcut". Although it's not really deviating from HTTP standards. I guess it was easier and more pragmatic for Stripe and users to implement an "Idempotency-Key" header instead of duplicating each POST endpoint with PUT and PATCH methods since they also allow partial updates. I guess (again) that they would also have to use/implement additional header (such as ETag or If-Match) to replicate current "Idempotency-Key" header behavior.
Disclaimer: This last paragraph is full of assumptions and I most probably miss a lot of internal details from Stripe API.
It is a huge shortcut to map CRUD operations to HTTP verbs POST, GET, PUT, DELETE. By the way, the definition of HTTP verbs defined in the HTTP RFCs (from RFC 1945 to RFC 7231) and the original thesis from Roy Fielding about REST (which is defining REST principles as an architectural style) never talk about one-to-one relationship between CRUD and PUT-GET-POST-DELETE.
While I understand that it might be confusing without deep-diving in long-long-lectures, the last RFC explains clearly what is the purpose of each HTTP verb including the difference between PUT and POST:
Therefore it would be perfectly valid to "create" a resource with both PUT and POST methods as well as "update" another one with, also, PUT and POST. It is actually even clearly stated with a few examples in the RFC. For instance in POST definition: I used to defined PUT and POST requests according their characteristics: the first one is idempotent, the second is not ... but could be. Therefore, in my understanding, it is perfectly valid to perform an "upsert" (insert or update) to a resource which doesn't exist yet but for which you already know the URL, it is indeed idempotent. For instance: A last piece of evidence is the first line of PUT section in RFC 7231: I hope it helps to clarify a little bit the topic.