SoapUI RESTful - HTTP Methods


Advertisements

The most-commonly-used HTTP methods are POST, GET, PUT, PATCH, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations, respectively. There are a number of other methods too, however they are utilized less frequently. Among these methods, OPTIONS and HEAD are used more often than others.

POST

The POST method is used to create new resources. It is 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 the parent and the service 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 the newly-created resource with the 201 HTTP statuses.

POST is neither safe nor idempotent. It is therefore recommended for non-idempotent resource requests.

Making two identical POST requests will result in two resources containing the same information. Sometimes, it throws an error message based on the type of services defined.

GET

The HTTP GET method is used to read or retrieve a representation of a resource. In successful response, GET returns a representation in XML or JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST).

According to the design of the HTTP specification, GET (along with HEAD) requests are used only to read data and not change it. Therefore, GET is considered as safe.

GET can be called without risk of data modification or corruption - calling it once has the same effect as calling it 10 times. Additionally, GET is idempotent, which means that making multiple identical requests leads to having the same result as a single request.

It is recommended not to expose unsafe operations via GET - it should never modify any resources on the server.

PUT

PUT is used to update the existing resources. PUT is used as a known resource URI with the request body that contains the updated representation of the original resource.

PUT can also be used to create a resource where the resource ID is chosen by the client instead of by the server. In other words, if PUT is used as a URI that contains the value of a non-existent resource ID.

POST is used to create new resources and provide the client-defined ID in the body representation. On successful update, it returns 200 (or 204 if not returning any content in the body) from a PUT.

If PUT is used for creation, it returns HTTP status 201 on successful creation. A body in the response is optional.

PUT is not a safe operation, since it modifies (or creates) the state on the server, however it is idempotent. If the user creates or updates a resource using PUT and then makes the same call again, the resource is still there and has the same state as it did with the first call.

It is recommended to keep PUT requests idempotent. It is strongly recommended to use POST for non-idempotent requests.

PATCH

PATCH is used to modify capabilities. The PATCH request only needs to contain the changes to the resource, not the complete resource. It resembles PUT, but the body contains a set of instructions describing how a resource currently residing on the server should be modified to produce a new version.

This means that the PATCH body should not just be a modified part of the resource, but should be in some kind of patch language such as JSON Patch or XML Patch.

PATCH is neither safe nor idempotent. A PATCH request can be issued in such a way as to be idempotent, which also helps prevent bad outcomes from collisions between two PATCH requests on the same resource in a similar time frame.

Collisions from multiple PATCH requests may be more dangerous than PUT collisions as some patch formats need to operate from a known base-point or else they will corrupt the resource.

Clients 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.

DELETE

DELETE is used to delete a resource identified by a URI. On successful deletion, it returns HTTP status 200 (OK) along with a response body, representation of the deleted item. Else, it returns HTTP status 204 (NO CONTENT) with no response body.

In other words, a 204 status with no body, or the JSEND-style response and HTTP status 200 are the recommended responses.

HTTP spec-wise, DELETE operations are idempotent. If the user deletes a resource, it's removed. Repeatedly calling DELETE on the same resource ends up with the same result: the resource is gone.

Calling DELETE on a resource a second time will often return a 404 (NOT FOUND), since it was already removed and therefore is no longer findable. This makes DELETE operations no longer idempotent, however, the end-state of the resource is the same. Returning a 404 is acceptable and communicates accurately with the status of the call.

soapui_restful_web_services.htm
Advertisements