RESTful API are communication gateways between service providers and their clients. They utilise HTTP verbs to standardise the way that clients can communicate with them, making them more easily accessible for client side developers.

The use of HTTP verbs in RESTful APIs gives the user (client side developer) a strong understanding of what a given endpoint is going to do. But, it should also be clearly understood by all, that the verbs true behaviour is purely implementation specific.

Let’s start with the actual verbs. RFC 7231 describes eight of the nine HTTP request methods (HTTP verbs) that can be used in RESTful APIs.

These are

• GET
  • Transfer a current representation of the target resource
• HEAD
  • Same as GET, but only transfer the status line and header section
• POST
  • Perform resource-specific processing on the request payload
• PUT
  • Replace all current representations of the target resource with the request payload
• DELETE
  • Remove all current representations of the target resource
• CONNECT
  • Establish a tunnel to the server identified by the target resource
• OPTIONS
  • Describe the communication options for the target resource
• TRACE
  • Perform a message loop-back test along the path to the target resource

And RFC 5789 describes the ninth method.

• PATCH
  • Change the target resource with the changes described in the request payload

The expectation is that the behaviour of the service matches the verb, in some way. But that’s purely up to the designer of the service. For example the DELETE verb will most likely not actually delete the data, rather it will likely soft delete (mark the data as deleted but keep it anyways).

There are disputes on when a given verb is appropriate, most often that dispute is whether to use PUT or POST for the creation or change of a given resource.

The RFC provides some guidance, PUT is used when the action is idempotent, and the client has control on the name of the resource (an example might be uploading an image to a user specific directory). In all other cases POST is appropriate.

Therefore PUT is best for creation when the client has control on the name of the resource. POST is better for all other cases.

For updates, PATCH is best, unless the expectation is for the client to provide the entire set of data (ie. a complete replacement) for that resource, in which case PUT is appropriate.

Designers are setting the terms of how clients will engage with the API when choosing which verb to use.