What is considered best practice when it comes to updating an object attribute in a database through a RESTful API?

For example, given a User model with firstName, lastName and age attributes, in order to update a user's age, would you rather:

• PUT a /api/users/:id/ endpoint with a json with firstName, lastName and age keys, (or even PATCH that endpoint only with the age key) or...
• POST a /api/users/:id/age/ endpoint with a json with a single age key?

CodePudding user response：

What is considered best practice when it comes to updating an object attribute in a database through a RESTful API?

The HTTP request is going to describe some kind of modification to a "resource"; the fact that your request handler makes modifications to the database is an implementation detail hidden behind the resource facade.

The identifier of the resource that you use to change information should be the same as the identifier of the resource used to read information. The motivation here is caching, and cache invalidation - by using the same URI for reads and writes, we make it possible for general purpose components to manage their caches correctly.

Therefore, if you are expecting clients to read values out of the database via /api/users/12345, then you should also encourage clients to write values via /api/users/12345.

HTTP methods describe the semantics of the request. Part of the point of the "uniform interface" constraint in REST is that all resources understand requests the same way.

So the choice of PUT vs POST depends on how you are communicating the edits you want in the body of the request.

On the web, where HTML browsers were ubiquitous (as opposed to HTML _editors), we always used HTML forms to provide clients with the information they needed to create their edit requests. It is okay to use POST.

But if your client is a document editor, than an alternative is to use remote authoring semantics, and have the client send as the request body a copy of its version of the document. That's the case where PUT is appropriate, when we're trying to tell the server "make your copy look like mine".

(When the resource is very large, then you might want to send just the changes; that's when we would use PATCH with a patch-document in the request body.)

Should age have its own resource? should it be part of the same resource that describes first name and last name? Both?

"It depends".

If the client is caching responses for two different resources that have the same information, then there will be windows where the cached responses are out of sync with each other. For information where that's going to create expensive problems, you'll want to make sure that information only shows up in one place.

With two pieces of information that change together, it makes perfect sense to treat them as part of the same resource. With information that changes for different reasons, you again need to look at how expensive is it if the information sits in cache too long, how expensive is it if we frequently invalidated cached responses, can we choose a caching strategy that is acceptable for all of the information?

For something like a user profile - age changes once a year, names typically change even less frequently than that, so it's probably going to work out OK if you throw it all into a single document with a single caching strategy.

Mixing volatile time sensitive information with information that is expensive to download makes optimal caching challenging -- avoid that combination if you can.