Understanding REST Request Methods

Best Practices: Testing the Other Verbs

The HyperText Transfer Protocol – HTTP – defines several methods (referred to as "verbs") that indicates the desired action to be performed on a resource. The resource is specified by the URI (Uniform Resource Identifier), more commonly, the URL. This resource may be pre-existing data or data that is generated dynamically, it depends on the server implementation. The server can be configured to support any combination of methods. The most common are: GET, POST, PUT, and DELETE, but there are several others. There is no limit to the number of methods that can be defined and this allows for future methods to be specified without breaking existing infrastructure.

The concept of idempotence is relevant to this discussion. If something is idempotent, then no matter how many times you do it, the result will always be the same. A very simple example comes from mathematics: multiplication by 1; no matter how many times you multiply any number by 1, the result will always be the same: the original number.

SOAP APIs, when sending over HTTP, can use only the POST verb, and the exact action depends on the SOAP method that is being called. REST, being an architectural style and not a standard, and makes full use of all the available verbs. (See the World Of API Testing section article SOAP vs. REST Challenges.) There is no definite answer to exactly what each verb should or should not do. When testing a RESTful API, you can use the following best practices as a starting point, but check with your in-house architect or development lead to find out what exactly your project adheres to.

POST

Out of the four discussed here POST is the only method that is assumed to be non-idempotent. This is the preferred method when creating new objects in an application, for example creating a new order. Every POST method call should result in a new object being created (or possibly deleted) in the database.

It is not uncommon, especially for legacy applications, that every single call in the entire API is implemented using the POST method. This is an indicator of architecture problems and lack of forethought. If there also are resource hierarchy problems, future enhancements will be difficult. As a tester you should be particularly cautious in this situation, and account for additional time for testing when doing estimates.

PUT

The PUT method should be idempotent. The word “should” indicates that the server is able to implement this method differently. A tester should flag such an implementation as an inconsistency.

PUT can still be used for creating objects, although since it is idempotent, repeatedly executing the same request will have the same end result as the first time. For example no matter how many times you send in a request to create that same customer ID, it should only be created once in the database.

DELETE

The DELETE method is idempotent; multiple requests should result in only one thing being deleted. As an example, consider the above scenario where multiple POST requests were sent to the server for a new order, resulting in multiple orders of the same product. A DELETE request should accept a unique identifier to remove only one of the products from the order, thereby sending the same DELETE request will result in the correct idempotent operation: the one instance of the product.

If the DELETE request were to accept, say, the product name, sending the request in multiple times would eventually remove all the products from the order, resulting in a non-idempotent implementation of this method. Again, as tester, such a situation should be brought to the attention of the development team. A more correct implementation of this “multi-delete” functionality would be a POST operation in combination with correctly crafted URL, such as:

/{order_number}/{product_name}/remove

GET

The GET operation is normally used to only retrieve information from the system. Nothing is added or changed, so it is more than idempotent, it is actually nullipotent – it has absolutely no side-effect on the data, other than possibly logging.

Summary

As we mentioned there can be "other verbs", when working with REST. In that case there are a few things to keep in mind:

  • Since REST does not have a standard, make sure everyone working on the product uses the same definition. This should be set by the development lead of your team.
  • As some of the verbs are not idempotent it is vital that everybody, especially your consumers in case of public APIs, are expecting the same results when using them.
  • Verify that the correct verb is being used. As some verbs can achieve the same results, make sure you are using the correct one. Both from a functionality and consistency standpoint.