If the documentation says it is a REST API, you could be justified in expecting all POST requests to be non-idempotent, and all other requests to be idempotent.
But it would still be reassuring to see this stated explicitly!
That's only if all calls are isolated to simply modifying state of objects, and not causing events. For example, if doing a PUT on a user to change their email kicks off an email to verify the account, then it's not idempotent in my mind.
It could be argued this is a departure from the standard, but on the other hand allowing PUT to have side-effects might be more user-friendly than an extra POST to a special "email invitation" resource. Would you prefer to see this behavior (as long as it was documented)?
Come on: that’s easily fixable if the provider cares: just assign an ID to every mutation operation. Never repeat the operation if called again.
In the real world even bigger players such as AdWords would time out on our bulk requests to them if making >100M changes, without giving any errors back (the jobs just simply tend to disappear; or the jobs never get submitted in the first place).
Truth is, you may or may not be discussing the appeal of the REST; but the issue in this context is solved already - and it’s only a matter of professionalism and therefore, the resources required to build something that just works.
But in the real world we get stoned students writing the majority of the APIs; having read a few how-to’s.
But it would still be reassuring to see this stated explicitly!