Skip to content

Update stop-using-put-for-updates.mdx #462

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ArchitectedDev wants to merge 2 commits into
base: development
Choose a base branch
from
Open

Update stop-using-put-for-updates.mdx #462

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
db31257
Update stop-using-put-for-updates.mdx
ArchitectedDev Jun 27, 2022
8b30bba
Update stop-using-put-for-updates.mdx
ArchitectedDev Jul 13, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 3 additions & 4 deletions content/documents/stop-using-put-for-updates.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,11 @@ Conversely, use `POST` when you want the ID to be auto-generated by the platform

`PUT` actually has a few nice qualities when used in the above scenarios:

1. `PUT` is idempotent, i.e. you shouldn't need to check if it has already been called, because calling it a second time will leave the resource in exactly the same state as calling it the first time. (`POST`, on the other hand, generally creates a new resource with each successive call.)
2. You generally don't have to worry about checking for existence. For example, if you want to assign a user to a group, you don't need to worry about creating a duplicate assignment - just `PUT` the assignment and it will either create a new one or overwrite the existing one.
1. You generally don't have to worry about checking for existence. For example, if you want to assign a user to a group, you don't need to worry about creating a duplicate assignment - just `PUT` the assignment and it will either create a new one or overwrite the existing one.

## Summary

| Use `POST` when... | Use `PUT` when... | Use `PATCH` when... |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| - You want to create a new resource where WE (the platform) are generating the ID. The new ID will be returned in the response body (as part of the full object), and the URI of the new resource will be returned in the Location response header. | - You want to create a new resource where YOU are providing the ID, use `PUT`. (No need to include the ID in the request body; it's in the URI.) | - You want to update an existing resource. |
| | - You want to completely replace a resource with another (same ID), use `PUT`. This is not common. - You want to update an existing resource. | - You want to "move" a resource. The old ID goes in the URI; the new one in the request body. |
| - You want to create a new resource where WE (the platform) are generating the ID. The new ID will be returned in the response body (as part of the full object), and the URI of the new resource will be returned in the Location response header. | - You want to create a new resource where YOU are providing the ID, use `PUT`. (The ID will need to be provided in both the URI and the request body to prevent the ID from being replaced with a generated ID from the platform.) | - You want to update an existing resource. |
| | - You want to completely replace a resource with another (same ID), use `PUT`. This is not common. - You want to update an existing resource. | - You want to "move" a resource. The old ID goes in the URI; the new one in the request body. |