CODEWITHSUNDEEP
restapihttpdesign-patterns
AndrewTet
AndrewTet

Reputation: 1182

Rest API Design: Why are path variables favored over the body

I've been having a discussion about REST API design at work and I'm hoping someone can answer a question for me.

Most of what I've read on REST API design best practices seem to agree that when doing a PUT, PATCH, or DELETE you should use the URI to identify the resource, and the body to pass any additional data.

So, in a route where you are making an update to the email of user 123, you would have something like this:

PUT /users/123

body:
{
  email: "[email protected]"
}

My question is why is it favored over something like this:

PUT /users

body:
{
  userId: 123,
  email: "[email protected]"
}

Pretty much everything I've read seems to agree that the first example is considered the best practice, but I've yet to find anything that explains why that is other than keeping it consistent with the GET requests. I'm not trying to argue against the best practices, just trying to understand why that is favored.

Upvotes: 0

Views: 245

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57249

Cache invalidation.

The resource identifier is also used as a cache key; on a successful unsafe request (which include PUT, PATCH, DELETE), general purpose components that are HTTP aware will know to invalidate any cached representations that match the target URI.

The key idea to understand is that the meta data (including the target-uri and the headers) informs general purpose components about the broad semantics of what is going on, so that they can do reasonable things in response.

Upvotes: 2

Related Questions