Win a copy of Kotlin in Action this week in the Kotlin forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic

JSON in REST PUT calls and full or partial objects  RSS feed

 
Scott Shipp
Ranch Hand
Posts: 223
12
Eclipse IDE IntelliJ IDE Java Scala Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
When a PUT is performed to update an existing resource what is the preferred approach? Is only information PUT that needs updated? Or is a FULL object required? Why or why not? If only the information that is being updated (or added as the case may be) is PUT, then there are some weird problems. How do you remove something? (User object needs JSON PUT to remove a second email address for instance.) If the full information is PUT every time, then could this be expensive on bandwidth and performance?
 
Bear Bibeault
Author and ninkuma
Marshal
Posts: 66207
151
IntelliJ IDE Java jQuery Mac Mac OS X
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
For all my REST interfaces, a PUT only needs the id and any values to be updated.
 
Ron McLeod
Saloon Keeper
Posts: 1600
232
Android Angular Framework Eclipse IDE Java Linux MySQL Database Redhat TypeScript
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
My understanding is that a PUT must include the full representation of the resource. Any attributes missing in a PUT are removed from the resource.

I have read about using the PATCH Method for HTTP to make selective changes to existing resources. I'm not sure how widely used it is, but I am considering using it with in a project that I am working on right now.
 
Scott Shipp
Ranch Hand
Posts: 223
12
Eclipse IDE IntelliJ IDE Java Scala Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Yeah it seems like those are the two approaches I have seen around.
 
Bear Bibeault
Author and ninkuma
Marshal
Posts: 66207
151
IntelliJ IDE Java jQuery Mac Mac OS X
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
If you think about it, the "full object" approach is really limiting, and dangerous. It would be impossible for clients to only know about part of the resource (for example, different permission levels might see more or less of the resource), and it makes it much too easy for clients to destroy the model by simply forgetting to include a property. What happens when new properties are added to the model? Any client who doesn't start using it immediately, removes it.

The obvious question for the partial approach is: so how do you get rid of a value? Most of my models make no distinction between null and other values. So, for example, setting a string property to the empty string. If there are rare circumstances where null is significant, it's the model's responsibility to set things correctly; not the client's.
 
Ron McLeod
Saloon Keeper
Posts: 1600
232
Android Angular Framework Eclipse IDE Java Linux MySQL Database Redhat TypeScript
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
The clients could do a GET and PUT combination. The GET returns the full representation (for that client), and the PUT provides a modified representation of what was received, where the modification may involve removing attributes. If the representation the client sees is limited based on their role, then that would need to be taken in to account when the client's PUT is prrocessed.
 
Bear Bibeault
Author and ninkuma
Marshal
Posts: 66207
151
IntelliJ IDE Java jQuery Mac Mac OS X
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Sure it's possible to do it that way, but that doesn't really alleviate any of the problems I outlined. But even so, the question would be: why? If the answer is to make it easier to null out values, well, I've already pointed out why that's not the best approach, in my opinion.

There is lots of divided thought on this. I'd say take the approach that best meets the needs of your API.

P.S. But to be "most correct", according to most resources, Ron's "full approach" would be applied to PUTs and partials to PATCHes. My APIs have no need for the distinction.
 
William Brogden
Author and all-around good cowpoke
Rancher
Posts: 13078
6
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
In a true RESTful architecture a PUT completely replaces the addressed resource or creates it if it does not exist.

To modify an existing resource, isn't a POST more appropriate?

Bill
 
Bear Bibeault
Author and ninkuma
Marshal
Posts: 66207
151
IntelliJ IDE Java jQuery Mac Mac OS X
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Actually, that's what PATCH is for. But being fairly new, support for PATCH is, er, patchy.

I've seen some APIs that hack POST to mean either create (no id) or patch (with id). But that's just not my approach.

P.S. Let it also be said that the origination of most of the APIs I'm supporting predate the inception of PATCH, and my documentation clearly points out the semantics of PUTs.
 
It is sorta covered in the JavaRanch Style Guide.
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!