With REST, should I use PUT or PATCH to edit a secondary ressource?

Question

So I have users and each user has a car. A user:

{
  name: 'Bob',
  car: {
    brand: 'Ford'
  }
}

To update Bob's car I could use an endpoint PUT /users/1 and update the entirety of Bob, or use an endpoint PATCH /users/1 and specify in the body that I only want to update Bob's car.

But if I want a route that only refers to Bob's car /users/1/car what method should I use to update the car? PUT, PATCH, or something else?

car is called a secondary resource of the user I believe, but in this case, I do not know what is the entity, is it the user or is it the car? If it's the car, then I believe I should use PUT, but if it is still the user then it should be PATCH.

https://stackoverflow.com/questions/24241893/should-i-use-patch-or-put-in-my-rest-api — Daniel A. White, Apr 17 '23 at 14:20

VoiceOfUnreason · Answer 1 · 2023-04-19T12:53:14.957

With REST, should I use PUT or PATCH to edit a secondary resource?

Careful - secondary resource can be understood to mean something very different from what you are describing here.

An important constraint in the REST architectural style is the uniform interface constraint. Among other things, this means that request semantics are the same for all target resources.

Therefore: PUT and PATCH messages that target /users/1/car should have the same semantics as PUT and PATCH messages that target /users/1 should have the same semantics as PUT and PATCH message that target /questions/76036040/with-rest-should-i-use-put-or-patch-to-edit-a-secondary-ressource.

Specifically: we use PUT when the request body is a representation of our desired state for the target resource. We use PATCH when the request body is a patch-document, which is to say a description of a set of changes that should be made to the target resource.

in this case, I do not know what is the entity, is it the user or is it the car? If it's the car, then I believe I should use PUT, but if it is still the user then it should be PATCH.

Doesn't matter - PUT and PATCH are about representations of resources, not representations of entities. Our REST API hides our domain entities behind a facade that looks like a web site; the semantics of the messages we are sending are expressed in the abstractions of the web site, not the underlying implementation.

So if my route is /users/1/car and changes the entirety of user 1 car, then it is PUT?

If the target URI is /users/1/car, and the payload is a complete replacement representation of the /users/1/car resource, then the method should be PUT.

If the target URI is /users/1/car, and the payload is a patch-document that describes a set of changes to the representation of the /users/1/car resource, then the method should be PATCH.

The fact that there is also a /users/1 resource which may be impacted by the changes in /users/1/car is not relevant to the question.

Note that sending a PATCH to /users/1/car with a patch document that describes a set of changes to /users/1 is completely nonsensical (it is misleading to general purpose HTTP components who don't know that the two resources are related to each other).

So if my route is /users/1/car and changes the entirety of user 1 car, then it is PUT? Because I had someone make the argument that it only changes a part of user 1 so it should be PATCH, but the route target user 1 car, not user 1. — François MENTEC, Apr 19 '23 at 07:22

With REST, should I use PUT or PATCH to edit a secondary ressource?

1 Answers1