Why is REST still so confusing to people?

Photo by Clément H on Unsplash

I’ve been interviewing a lot of people lately and one thing that i’ve seen time and time again, even from experienced developers is that they just don’t understand how to properly design REST api’s.

If you asked 100 software developers if they know what REST is and how to design REST api’s you’d probably get damn near 100 of them saying yes. Funny thing is when you have them design a couple simple rest endpoints, they do all kinds of things that do not follow the REST conventions.

My interview is fairly simple and straightforward, or so i thought, and the intention of the question is to see what level of understanding you have of REST api’s.

My interview question is 2 fold:
1) Design a REST endpoint for fetching a particular user
2) Design a REST endpoint for updating that particular user

These are some of the answers I see far too often, especially from some fairly senior developers:

GET /users/getUser/1 for fetching a user

POST /users/updateUser for updating a user

The reason these are wrong is because by convention, the HTTP verb represents an action and we should use nouns to represent resources upon which the verb is acting.

The correct version of GET /users/getUser/1 is simply GET /users/1. By using the HTTP verb GET, it implies that you are retrieving some data. This means that there is absolutely no need for getUser anywhere in the URL. You can think of it like this GET /users/1 = “get user where id = 1".

The correct version of POST /users/updateUser is simply PUT or PATCH /users/1. By using the HTTP verb PUT or PATCH, it implies that you are updating some data. This means that there is no need for updateUser anywhere in the URL. You can think of it like this PUT or PATCH /users/1 = “update user where id = 1”.

PUT vs PATCH

Many people think that a PUT request is synonymous with a PATCH request, but they in fact have a different intention. Typically a PUT request is used to replace an entire record and a PATCH request is used to update a partial record.

There are many places to read up on this on the web including here, here, and here.


There are no hard and fast rules with REST and there are plenty of circumstances where the REST rules need to be bent to fit your needs, but there are also so many common use cases that don’t need to be done 1.289432 million different ways. Simple REST operations should follow the the simple REST conventions. Period.