HTTP verbs

HTTP verbs are a set of methods that can be used to perform actions on a specified resource (URI). You send them along with the request to tell the server what you want to do.

Most HTTP verbs correspond to CRUD operations. Some HTTP verbs allow you to send a body along with your request. The body contains extra information that might be required to perform a certain action. A POST request, for instance, contains a body that gives the server information on what entity to create.

Most common HTTP verbs

HTTP Verb	CRUD	Description	Request Body?
GET	Read	Should only retrieve data from the resource.	No
POST	Create	Submit an entity.	Yes
POST	Action	Trigger an action.	No
PUT	Modify	Use PUT if you want to update all fields (because all fields must be provided, and those not provided get nulled).	Yes
PATCH	Modify	Use PATCH if you want to partially update some fields (all fields not provided remain as they are).	Yes
DELETE	Delete	Deletes the specified resource.	Optional
OPTIONS	-	Used to request the possible communication options.	Optional

The HTTP verbs we use are GET, POST, PUT, PATCH, DELETE, and OPTIONS. API calls made from the browser often first send an OPTIONS call to the API. The API responds with the possible communication options, such as the supported HTTP verbs, headers, etc. Therefore, we make our APIs support OPTIONS calls.

For more on the HTTP verb OPTIONS, please refer to: Mozilla Developer Docs.

For more information on how to support OPTIONS calls and CORS, see the Cookbook.

warning

Don’t use an HTTP verb to perform an action that does not correspond to the verb. For instance, don’t use a POST request to only retrieve (GET) data.

Post vs Patch example

To create an operation to expire a customer, it is possible to create an endpoint expire and call it with the POST verb:

POST /v1/customers/{id}/expire

However, this could be confused with creating an expiration resource for a customer. For this use case, a PATCH request to update the expire property of a customer is suggested:

PATCH /v1/customers/{id}
{
    "data": {
        "expire": "true"
    }
}

It is important to consider if the operation is significant enough to own a resource (using POST) or if it is just a toggle or metadata property that can be set using PATCH.

Put vs Patch example

To update a resource, either update the full record (PUT) or update it partially (PATCH).

If all fields need updating, use PUT:

PUT /v1/customers/{id}
{
    "name": "ACME studio",
    "postalcode": "12345",
    "street": "Studio street",
    ...
    "houseNumber": "1-7"
}

If only one field needs updating, use PATCH:

PATCH /customers/v1/{id}
{
    "name": "ACME studio"
}