REST – PUT vs POST, https://restfulapi.net/rest-put-vs-post/
POST is NOT idempotent. So if you retry the request N times, you will end up having N resources with N different URIs created on server.
PUT method is idempotent. So if you send retry a request multiple times, that should be equivalent to single request modification.
REST API Tutorial, https://restfulapi.net/
1.1.Guides
Guidelines for the API design and development at adidas
This is a general design guide for networked APIs. It has been used inside Google since 2014 and is the guide that Google follows when designing Cloud APIs and other Google APIs. This design guide is shared here to inform outside developers and to make it easier for us all to work together.
Guidance
All Google API interfaces must provide a major version number, which is encoded at the end of the protobuf package, and included as the first part of the URI path for REST APIs. If an API introduces a breaking change, such as removing or renaming a field, it must increment its API version number to ensure that existing user code does not suddenly break.