Put or post?

Create, update, and HTTP idempotence

Developers who build rest APIs have great misunderstandings and confusions about when to use http put and post. Some people think that post is used to create resources, while put is used to update resources. Others think that put is used to create and post is used to change resources. These two statements are not exactly true.

Generally, developers map each HTTP method to a crup operation.

Crud HTTP
Create post
Read get
Update put
Delete Delete

This is true, and the get and delete operations are clear, but the HTTP methods corresponding to create and update depend on the idempotence.

State Uniformity

Status uniformity is an important concept in HTTP specifications. It specifies that the resources on the server are in the same status when the same HTTP request is executed multiple times. Get, head, put, and delete all have this feature, but post does not.

To facilitate state uniformity, we will use an account set ("/Accounts"). For simplicity, we assume that each account resource has three attributes: givenname, surname, and status.

Assume that you submitted an update request using the http put method. In the request body, you set the givenname and surname values to "John" and "Smith" respectively ". Then you submitted another http put request. This time, you set the value of givenname to "Johnny ". Is it idempotent? No. Why? In the gap between the two requests, other requests may have changed the server status of the account resource. For example, the status value may have changed to "blocked" between the two requests ". When the demo request is submitted repeatedly, the Account resources on the server cannot be in the same status.

Request:

?

12345

HTTP/1.1 PUT /accounts/abcdef1234{      “givenName”: “John”,      “surname”: “Smith”}

 

The possible account status after these two requests. (Affected by the side effects of other requests ):

?

12345

{      “givenName”: “John”,      “surname”: “Smith”,      “status”: “enabled”}

 

Or

?

12345

{      “givenName”: “John”,      “surname”: “Smith”,      "status”: “disabled”}

 

ReferenceDino ChiesaDescribed,"PutIt means to submit a resource-use a different thing to completely replace all accessible resources under a given URL ."To use a put request, you must send all accessible properties/values, not just those you want to change. If the status value "disabled" is added when givenname and surname are sent, the call is idempotent and the side effects are eliminated. Idempotence is a basic attribute of HTTP specifications and must ensure web interoperability and scale.

Finally, we should point out that the HTTP status uniformity can only be applied to the server status-non-client. For example, a client successfully sends a unified server-side request and immediately resends the request again, but returns an error (for example, it may be because it violates some constraints on the server ), this is still 'legal 'for HTTP. This request does not affect the server resource status, and the HTTP idempotence is not damaged.

Http post vs HTTP PUT

Now that you know the state uniformity, which method should you use when performing the creation and update operations? The following is a quick reference for rational use of these methods.

Create

If you do not know the resource identifier, you should use post to create the resource. When using post to create a resource, returning the "201 created" status and creating a resource location are good practices, because the location of the newly created resource is unknown at the time of submission. This allows the client to access the newly created resources later, if necessary.

?

1234	HTTP/1.1 POST /accounts{       …}

 

Response:

?

12	201 CreatedLocation: https://api.stormpath.com/accounts/abcdef1234

 

Use put when you allow the client to specify the resource identifier of the newly created resource. But remember, because put is idempotent, you must send all possible values.

?

1234567

HTTP/1.1 PUT /accounts/abcdef1234 {      “givenName”: “John”,      “surname”: “Smith”,      “status”: “enabled”}

Update

You can use post to update all or part of values.

?

12345

HTTP/1.1 POST /accounts/abcdef1234{      “status”: “disabled”}Response 200 OK

 

If you want to use put to update a resource, you must update all attributes of the resource. You must send all attribute values in the put request to ensure idempotence.

?

123456

HTTP/1.1 PUT /accounts/abcdef1234{      //FULL RESOURCE UPDATE      “givenName”: “J”,      “surname”: “Smith”,      “status”: “Enabled”}

 

You can also use post to send all values so that the server status is the same as the result for processing put requests-this is not required by HTTP specifications. Note that idempotence is strongly related to the cache of the HTTP Cache Server, and post requests are usually non-cached. If you have a cold side effect on caching, you can use post to perform all or part of updates.

Post is the only method with different statuses. The HTTP specification is also widely defined and generally defined as a "server processing instruction ". This means that any processing in the POST request is "safe.

Finally, pay attention to another method called patch that has not been completed in the HTTP specification. Patch is a substitute for post when some updates are executed. However, because post can already handle some updates, the HTTP association does not seem to be in a rush to approve and complete the patch. However, if approved, the patch will add post as an inconsistent HTTP Method in another State.