...
The request body must contain exactly one item to be saved in the API application. Performing a POST with identical natural keys to a resource already in the data store must perform an update rather than create a new resource (colloquially known as an "upsert"). A POST operation must not allow a desired unique identifier to be provided to the REST API.
See Data Strictness for more information about validation of the request body.
...
The response could contain the item that has just been created, optionally including the same metadata used in a GET response.
Response Headers
...
If the application supports ETags , then the ETag must be provided in an Etag header. Example:
...
The following status codes must be supported for POST responses:
Status Code | Meaning | When to Use |
|---|---|---|
200 | OK | The item was updated ("upsert"). |
201 | Created | The item was created. |
400 | Bad Request | The request was invalid and cannot be completed. See the response body for specific validation errors. |
401 | Unauthorized | The request requires authentication. The OAuth bearer token was either not provided or is invalid. |
403 | Forbidden | The request cannot be completed in the current authorization context. |
404 | NotFound | GET by ID request where the identifier does not exist. |
405 | Not Allowed | The API is only intended for reads, or the |
500 | Server Error | An unhandled error occurred on the server. |
Other HTTP status codes may be used as needed for specific situations.