The Dev World – Sergio Lema

There are many HTTP verbs: GET, POST, PUT… All have a different meaning and usage.

Not using the adequate verb makes the API harder to read and understand.

In this article, I describe the main HTTP verbs to use in a regular RESTful application.

GET

Use GET to read information from the server.

It can be a single entity or a list of entities.

The thing is that using the GET verb, the only action done in the server is reading information. No information must be updated or deleted.

Examples:

• Read all the vehicles: GET /vehicles
• Read a single vehicle: GET /vehicles/123
• Read all the vehicles from France: GET /country/france/vehicles

POST

On the other side, I use the POST verb to send information to the server to modify some content.

It could be adding a new entity or performing a batch operation.

There are two main differences with the GET verb. The POST verb accepts a body with the request. And the POST verb, by definition, is not idempotent. This means that repeating the same request does not necessarily produce the same output.

Let’s say I want to create a new vehicle in my application. Using POST the first time will create the vehicle and it returns me its Id. The second time I send the same request, it may return me a different Id, or it may return me an error as duplicated data.

Examples:

• Create a new vehicle: POST /vehicles (with a body)
• Search for vehicles with some criteria: POST /vehicles/search (with a body)
• Buy the content of my basket: POST /basket/buy

PUT

I use the PUT verb when I want to replace an entity completely.

As with the POST verb, put accepts a body. But PUT is idempotent. I can send the request to replace an entity any time I want, it will always replace the same entity with the same content.

Example:

• Replace a vehicle: PUT /vehicles/123 (with a body)

PATCH

I use PATCH also to update an entity in the system. But the difference with PUT is that I only update some fields with PATCH, leaving the rest unchanged.

Examples:

• Replace the km of a vehicle: PATCH /vehicles/123/km/5000
• Replace the color of a vehicle: PATCH /vehicles/123/color/red
• Replace many fields: PATCH /vehicles/123 (with a body)

DELETE

The meaning of the DELETE verb is quite self-explanatory. I use it when I want to delete an item from the database.

It can be a soft delete (adding a flag which marks the entity as unavailable) or a hard delete (delete the row from the database).

Examples:

• Delete a vehicle from the database: DELETE /vehicles/123
• Remove an item from my basket: DELETE /basket/item/456

HEAD

The last verb I use in my RESTful applications is HEAD. I use the HEAD verb to verify the existence of an entity.

The HEAD verb responds with no body. This means that I must use this verb when an answer only based on the HTTP response code is enough.

Examples:

• Check if the vehicle exists: HEAD /vehicles/123
• Check if my order was sent: HEAD /order/123/status/sent

Conclusion

Here is a brief summary of the main HTTP verbs used in a RESTful application.

Verb	Usage	Example
GET	To read data	It accepts no body
POST	To upload data	It accepts a body. It’s not idempotent
PUT	To replace a complete entity	It accepts a body. It’s idempotent
PATCH	To replace part of an entity	It accepts a body. It’s idempotent
DELETE	To delete an entity	It accepts no body.
HEAD	To verify the existence of an entity	It accepts no body. It responds with no body.