From db31257ba78100fbd26ae921adb1b4875ef83ce3 Mon Sep 17 00:00:00 2001 From: Andrew Sutherland Date: Mon, 27 Jun 2022 17:25:57 +1000 Subject: [PATCH 1/2] Update stop-using-put-for-updates.mdx Removing statements that incorrectly refer to PUT requests in the OrderCloud API as being idempotent as this will typically cause the resource IDs to be regenerated by the platform. --- content/documents/stop-using-put-for-updates.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/content/documents/stop-using-put-for-updates.mdx b/content/documents/stop-using-put-for-updates.mdx index a0110195..24ebd682 100644 --- a/content/documents/stop-using-put-for-updates.mdx +++ b/content/documents/stop-using-put-for-updates.mdx @@ -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. | \ No newline at end of file +| - 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`. | - 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. | From 8b30bba670d1c7685174e36c0dc60f2970762b3a Mon Sep 17 00:00:00 2001 From: Andrew Sutherland Date: Thu, 14 Jul 2022 09:03:47 +1000 Subject: [PATCH 2/2] Update stop-using-put-for-updates.mdx --- content/documents/stop-using-put-for-updates.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/documents/stop-using-put-for-updates.mdx b/content/documents/stop-using-put-for-updates.mdx index 24ebd682..836ec5e9 100644 --- a/content/documents/stop-using-put-for-updates.mdx +++ b/content/documents/stop-using-put-for-updates.mdx @@ -40,5 +40,5 @@ Conversely, use `POST` when you want the ID to be auto-generated by the platform | 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`. | - You want to update an existing resource. | +| - 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. |