HTTP Methods also called as HTTP Verbs. Let's discuss about it how and when to use them in our Web API projects.
The most commonly used HTTP Verbs are POST, GET, PUT, PATCH and DELETE.These correspond to create, read, update and delete (or CRUD) operation, respectively.
Below is the table summarizing recommended return values of the primary HTTP methods in combination with the resource URIs:
Here is the details description of the HTTP methods.
POST - The POST verb is mostly used for **create** new resources. In particular, it's used to create subordinate resources. That is, subordinate to some other (e.g parent) resource. In other words, when creating a new resource, POST to parent and the services takes care of associating the new resource with the parent, assigning an ID (new resource URI), etc.
On successful creation, return HTTP status 201, returning a Location header with a link to newly created resource with the 201 HTTP status.
GET - The HTTP GET verb is used to **read** (or retrieve) a representation of a resource. In the pass case, GET returns a representation in XML or JSON and an HTTP response code 200 (OK). In an error case, it most often returns 404 (NOT FOUND) or 400 (BAD REQUEST).
According to the design of the HTTP specification, GET (along with head) request are used only to read data and change it. Therefore, when used this way, they are considered safe. That is, they can called without risk of data modification or corruption - calling it once has the same effect as calling it 10 times, or none at all. Additionally GET (and Head) is idempotent, which means that making multiple identical requests ends up having the same result as a single request.
Do not expose unsafe operations via GET - it should never modify any resources on the server.
PUT - PUT verb is most often used for **update** data, PUT-ing to a known resource URI with request body containing the newly updated representation of the original resource.
However, PUT can also be used to create in the case where the resource ID is chosen by the client instead of by the server. In other words, if the PUT is to a URI that contains the value of a non-existing resource ID. Again, the request body contains a resource representation.
Alternatively, use POST to create new resource and provide the client-defined ID in the body representation - presumably to a URI that doesn't include the ID of the resource (see POST below).
On successful update, return 200 (or 204 if not returning any content in body) from a PUT. If using PUT for create, return HTTP status 201 on successful creation. A body in the response is optional - providing one consumes more bandwidth. It is not necessary to return a link via Location header in the creation case since the client already set the resource ID.
PUT is not a safe operation, in that it modifies (or creates) state on the server, but it is idempotent. In other words, if you create or update a resource using PUT and then make same call again, the resource is still there and still has the same state as it did with the first call.
If, for instance, calling PUT on resource increments a counter within the resource, the call is no longer idempotent. Sometimes that happens and it may be not enough to document that the call is not indepotent. However, it's recommended to keep PUT requests idempotent. It is strongly recommended to use POST for non idempotent requests.
PATCH - verb (method) is used for **modify** capabilities. The PATCH request only needs to contain the changes to the resource, not the complete resource.
This resembles PUT, but the body contains a set of instructions describing how a resource currently residing on the server should be modified to product a new version. This means that the PATCH body should not just a modified part of resource, but in some kind of patch language like JSON Pathc or XML Patch.
PATCH is neither safe nor idempodent. However, a PATCH request can be issues in such a way as to be indempotent, which also helps prevent bad outcomes from collisions between two PATCH requests on the same resource in similar time frame. Collisions from multiple PATCH requests may be more dangerous that PUT collisions because some patch format need to operate from a known base-point or else they will corrupt the resource. Client using this kind of patch application should use a conditional request such that the request will fail if the resource has been updated since the client last accessed the resource. For example, the client can use a strong ETag in an If-Match header on the PATCH request.
DELETE - DELETE is pretty easy to understand. It is used to **delete** a resource identified by URI.
On successful deletion, return HTTP status 200 (OK) along with a response body, perhaps the representation of the deleted item (often demand too much bandwidth), or a wrapped response (see Return Values below). Either that or return HTTP status 204 (NO CONTENT) with no response body. In other words, a 204 status with no body, or the JSEND-style responce and HTTP status 200 are the recommended responses.
HTTP-spec-wise, DELETE operations are idempotent. If you DELETE a resource, it's removed. Repeatedly calling DELETE on that resource ends up the same: the resource is gone. If calling DELETE say, decrements a counter (within resource), the DELETE call is no longer idempotent. As mentioned previously, usage statistics and measurements may be updated while still still considering the service idempotent as long as no resource data is changed. Using POST for non-idempotent resource requests is recommended.
There is a caveat about DELETE idempotent, however. Calling DELETE on the resource a second time will often return a 404 (NOT FOUND) since it was already removed and therefore is no longer searchable. This, by some opinions, makes DELETE option no longer idempotent, the end-state of the resource is the same. Returning a 404 is acceptable and communicates accurately the status of the call.
The most commonly used HTTP Verbs are POST, GET, PUT, PATCH and DELETE.These correspond to create, read, update and delete (or CRUD) operation, respectively.
Below is the table summarizing recommended return values of the primary HTTP methods in combination with the resource URIs:
| HTTP Verb | CRUD | Entire Collection (e.g. /customers) | Specific Item (e.g. /customers/{id}) |
|---|---|---|---|
| POST | Create | 201 (Created), 'Location' header with link to /customers/{id} containing new ID. | 404 (Not Found), 409 (Conflict) if resource already exists.. |
| GET | Read | 200 (OK), list of customers. Use pagination, sorting and filtering to navigate big lists. | 200 (OK), single customer. 404 (Not Found), if ID not found or invalid. |
| PUT | Update/Replace | 404 (Not Found), unless you want to update/replace every resource in the entire collection. | 200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid. |
| PATCH | Update/Modify | 404 (Not Found), unless you want to modify the collection itself. | 200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid. |
| DELETE | Delete | 404 (Not Found), unless you want to delete the whole collection—not often desirable. | 200 (OK). 404 (Not Found), if ID not found or invalid. |
Here is the details description of the HTTP methods.
POST - The POST verb is mostly used for **create** new resources. In particular, it's used to create subordinate resources. That is, subordinate to some other (e.g parent) resource. In other words, when creating a new resource, POST to parent and the services takes care of associating the new resource with the parent, assigning an ID (new resource URI), etc.
On successful creation, return HTTP status 201, returning a Location header with a link to newly created resource with the 201 HTTP status.
GET - The HTTP GET verb is used to **read** (or retrieve) a representation of a resource. In the pass case, GET returns a representation in XML or JSON and an HTTP response code 200 (OK). In an error case, it most often returns 404 (NOT FOUND) or 400 (BAD REQUEST).
According to the design of the HTTP specification, GET (along with head) request are used only to read data and change it. Therefore, when used this way, they are considered safe. That is, they can called without risk of data modification or corruption - calling it once has the same effect as calling it 10 times, or none at all. Additionally GET (and Head) is idempotent, which means that making multiple identical requests ends up having the same result as a single request.
Do not expose unsafe operations via GET - it should never modify any resources on the server.
PUT - PUT verb is most often used for **update** data, PUT-ing to a known resource URI with request body containing the newly updated representation of the original resource.
However, PUT can also be used to create in the case where the resource ID is chosen by the client instead of by the server. In other words, if the PUT is to a URI that contains the value of a non-existing resource ID. Again, the request body contains a resource representation.
Alternatively, use POST to create new resource and provide the client-defined ID in the body representation - presumably to a URI that doesn't include the ID of the resource (see POST below).
On successful update, return 200 (or 204 if not returning any content in body) from a PUT. If using PUT for create, return HTTP status 201 on successful creation. A body in the response is optional - providing one consumes more bandwidth. It is not necessary to return a link via Location header in the creation case since the client already set the resource ID.
PUT is not a safe operation, in that it modifies (or creates) state on the server, but it is idempotent. In other words, if you create or update a resource using PUT and then make same call again, the resource is still there and still has the same state as it did with the first call.
If, for instance, calling PUT on resource increments a counter within the resource, the call is no longer idempotent. Sometimes that happens and it may be not enough to document that the call is not indepotent. However, it's recommended to keep PUT requests idempotent. It is strongly recommended to use POST for non idempotent requests.
PATCH - verb (method) is used for **modify** capabilities. The PATCH request only needs to contain the changes to the resource, not the complete resource.
This resembles PUT, but the body contains a set of instructions describing how a resource currently residing on the server should be modified to product a new version. This means that the PATCH body should not just a modified part of resource, but in some kind of patch language like JSON Pathc or XML Patch.
PATCH is neither safe nor idempodent. However, a PATCH request can be issues in such a way as to be indempotent, which also helps prevent bad outcomes from collisions between two PATCH requests on the same resource in similar time frame. Collisions from multiple PATCH requests may be more dangerous that PUT collisions because some patch format need to operate from a known base-point or else they will corrupt the resource. Client using this kind of patch application should use a conditional request such that the request will fail if the resource has been updated since the client last accessed the resource. For example, the client can use a strong ETag in an If-Match header on the PATCH request.
DELETE - DELETE is pretty easy to understand. It is used to **delete** a resource identified by URI.
On successful deletion, return HTTP status 200 (OK) along with a response body, perhaps the representation of the deleted item (often demand too much bandwidth), or a wrapped response (see Return Values below). Either that or return HTTP status 204 (NO CONTENT) with no response body. In other words, a 204 status with no body, or the JSEND-style responce and HTTP status 200 are the recommended responses.
HTTP-spec-wise, DELETE operations are idempotent. If you DELETE a resource, it's removed. Repeatedly calling DELETE on that resource ends up the same: the resource is gone. If calling DELETE say, decrements a counter (within resource), the DELETE call is no longer idempotent. As mentioned previously, usage statistics and measurements may be updated while still still considering the service idempotent as long as no resource data is changed. Using POST for non-idempotent resource requests is recommended.
There is a caveat about DELETE idempotent, however. Calling DELETE on the resource a second time will often return a 404 (NOT FOUND) since it was already removed and therefore is no longer searchable. This, by some opinions, makes DELETE option no longer idempotent, the end-state of the resource is the same. Returning a 404 is acceptable and communicates accurately the status of the call.
