How to use HTTP request methods correctly in REST APIs?

Question

In my search to understand the HTTP request methods, particularly PUT since I have apparently been using it all wrong, I have stumbled upon a lot of quotes stating “PUT doesn’t belong in REST APIs” and “One should only use GET and POST in modern APIs”.

This just makes me wonder, why would you not use PUT or PATCH or DELETE etc. in REST APIs? Isn’t it what they are there for? To be used because they help with semantics and structure etc.?

Could it have something to do with e.g. the methods receiving the request mainly being methods that directs the data to other methods like the database methods where they are then handled? I’ve used PUT when wanting to update a document, but never has it overwritten a document, even though I only sent part of the data to it.

There is an example of this below, using Express and MongoDB (showing a put method in Express).

app.put('/users/:id', (req, res, next) => {
    let id = req.params.id;
    userService.getOneUser({_id: ObjectID(id)}).then((user) => {

        let updatedData = req.body;

        userService.updateUser(user._id, updatedData)
           .then((doc) => res.json(doc))
           .catch((err) => errorHandler(err, res, next));

    }).catch((err) => errorHandler(err, res, next));
})

Basically my question is: In relating to the above statements, how do you use these methods correctly in REST APIs and when do you use them?

EDIT: Example on two references:

PUT doesn't belong in REST API

Only use GET and POST - see third comment on question

@cassiomolin Edited question for two references, but people around me have been saying the same thing. — , Mar 07 '19 at 12:50

score 1 · Answer 1 · edited Oct 07 '21 at 12:12

I have stumbled upon a lot of quotes stating “PUT doesn’t belong in REST APIs” and “One should only use GET and POST in modern APIs”.

I wouldn't put much stock in those quotes - they imply a lack of understanding about REST, HTTP, and how everything is supposed to fit together.

I'd suggest starting with Jim Webber, who does have a good understanding.

HTTP is an application protocol, whose application domain is the transfer of documents over a network.

PUT, PATCH, DELETE are all perfectly fine methods for describing changes to a document. I GET a document from you, I use my favorite HTTP aware editor/library to make changes to the document, I send you a request describing my changes to the document, you get to figure out what to do on your end.

This just makes me wonder, why would you not use PUT or PATCH or DELETE etc. in REST APIs? Isn’t it what they are there for? To be used because they help with semantics and structure etc.?

One reason that you might not: your media type of choice is HTML -- HTML has native support for links (GET) and forms (GET/POST), but not a lot of direct support in the way of involving the other methods in the flow. You can use code-on-demand, for those clients that support it.

Could it have something to do with e.g. the methods receiving the request mainly being methods that directs the data to other methods like the database methods where they are then handled? I’ve used PUT when wanting to update a document, but never has it overwritten a document, even though I only sent part of the data to it.

An important thing to understand about HTTP methods is that they describe semantics, not implementations. Here's Fielding writing in 2002:

HTTP does not attempt to require the results of a GET to be safe. What it does is require that the semantics of the operation be safe, and therefore it is a fault of the implementation, not the interface or the user of that interface, if anything happens as a result that causes loss of property

In the specific case of PUT, there's an extra hint at the implication of the semantics

A successful PUT of a given representation would suggest that a subsequent GET on that same target resource will result in an equivalent representation being sent in a 200 (OK) response. However, there is no guarantee that such a state change will be observable....

I think Triynko raises a good point:

URIs identified in most modern apps ARE NOT resources to be replaced, updated, etc. They're not documents. They're PROCEDURES being called.

If you are creating a procedure focused API, as opposed to a resource focused API, then there is a decent probability that PUT/PATCH/DELETE aren't actually providing benefits that justify the extra complexity.

One hint that you are procedure focused: how much attention are you paying to cache invalidation? Part of the point of accepting a "uniform interface" constraint is that you want the capabilities that generic components can provide, and in HTTP, caching is a big deal.

How to use HTTP request methods correctly in REST APIs?

1 Answers1