How to do PATCH properly in strongly typed languages based on Spring - example
According to my knowledge:
-
PUT- update object with its whole representation (replace) -
PATCH- update object with given fields only (update)
I'm using Spring to implement a pretty simple HTTP server. When a user wants to update his data he needs to make a HTTP PATCH to some endpoint (let's say: api/user). His request body is mapped to a DTO via @RequestBody, which looks like this:
class PatchUserRequest {
@Email
@Length(min = 5, max = 50)
var email: String? = null
@Length(max = 100)
var name: String? = null
...
}
Then I use an object of this class to update (patch) the user object:
fun patchWithRequest(userRequest: PatchUserRequest) {
if (!userRequest.email.isNullOrEmpty()) {
email = userRequest.email!!
}
if (!userRequest.name.isNullOrEmpty()) {
name = userRequest.name
}
...
}
My doubt is: what if a client (web app for example) would like to clear a property? I would ignore such a change.
How can I know, if a user wanted to clear a property (he sent me null intentionally) or he just doesn't want to change it? It will be null in my object in both cases.
I can see two options here:
- Agree with the client that if he wants to remove a property he should send me an empty string (but what about dates and other non-string types?)
- Stop using DTO mapping and use a simple map, which will let me check if a field was given empty or not given at all. What about request body validation then? I use
@Validright now.
How should such cases should be properly handled, in harmony with REST and all good practices?
EDIT:
One could say that PATCH shouldn't be used in such an example, and I should use PUT to update my User. But what about model changes (e.g. adding a new property)? I would have to version my API (or the user endpoint alone) after every User change. E.g. I would have api/v1/user endpoint which accepts PUT with an old request body, and api/v2/user endpoint which accepts PUT with a new request body. I guess it's not the solution and PATCH exists for a reason.
Solution 1:
TL;DR
patchy is a tiny library I've come up with that takes care of the major boilerplate code needed to properly handle PATCH in Spring i.e.:
class Request : PatchyRequest {
@get:NotBlank
val name:String? by { _changes }
override var _changes = mapOf<String,Any?>()
}
@RestController
class PatchingCtrl {
@RequestMapping("/", method = arrayOf(RequestMethod.PATCH))
fun update(@Valid request: Request){
request.applyChangesTo(entity)
}
}
Simple solution
Since PATCH request represent changes to be applied to the resource we need to model it explicitly.
One way is to use a plain old Map<String,Any?> where every key submitted by a client would represent a change to the corresponding attribute of the resource:
@RequestMapping("/entity/{id}", method = arrayOf(RequestMethod.PATCH))
fun update(@RequestBody changes:Map<String,Any?>, @PathVariable id:Long) {
val entity = db.find<Entity>(id)
changes.forEach { entry ->
when(entry.key){
"firstName" -> entity.firstName = entry.value?.toString()
"lastName" -> entity.lastName = entry.value?.toString()
}
}
db.save(entity)
}
The above is very easy to follow however:
- we do not have validation of the request values
The above can be mitigated by introducing validation annotations on the domain layer objects. While this is very convenient in simple scenarios it tends to be impractical as soon as we introduce conditional validation depending on the state of the domain object or on the role of the principal performing a change. More importantly after the product lives for a while and new validation rules are introduced it's pretty common to still allow for an entity to be update in non user edit contexts. It seems to be more pragmatic to enforce invariants on the domain layer but keep the validation at the edges.
- will be very similar in potentially many places
This is actually very easy to tackle and in 80% of cases the following would work:
fun Map<String,Any?>.applyTo(entity:Any) {
val entityEditor = BeanWrapperImpl(entity)
forEach { entry ->
if(entityEditor.isWritableProperty(entry.key)){
entityEditor.setPropertyValue(entry.key, entityEditor.convertForProperty(entry.value, entry.key))
}
}
}
Validating the request
Thanks to delegated properties in Kotlin it's very easy to build a wrapper around Map<String,Any?>:
class NameChangeRequest(val changes: Map<String, Any?> = mapOf()) {
@get:NotBlank
val firstName: String? by changes
@get:NotBlank
val lastName: String? by changes
}
And using Validator interface we can filter out errors related to attributes not present in the request like so:
fun filterOutFieldErrorsNotPresentInTheRequest(target:Any, attributesFromRequest: Map<String, Any?>?, source: Errors): BeanPropertyBindingResult {
val attributes = attributesFromRequest ?: emptyMap()
return BeanPropertyBindingResult(target, source.objectName).apply {
source.allErrors.forEach { e ->
if (e is FieldError) {
if (attributes.containsKey(e.field)) {
addError(e)
}
} else {
addError(e)
}
}
}
}
Obviously we can streamline the development with HandlerMethodArgumentResolver which I did below.
Simplest solution
I thought that it would make sense to wrap what've described above into a simple to use library - behold patchy. With patchy one can have a strongly typed request input model along with declarative validations. All you have to do is to import the configuration @Import(PatchyConfiguration::class) and implement PatchyRequest interface in your model.
Further reading
- Spring Sync
- fge/json-patch
Solution 2:
I have had the same problem, so here are my experiences / solutions.
I would suggest that you implement the patch as it should be, so if
- a key is present with a value > the value is set
- a key is present with an empty string > the empty string is set
- a key is present with a null value > the field is set to null
- a key is absent > the value for that key is not changed
If you don't do that, you'll soon get an api which is hard to understand.
So I would drop your first option
Agree with the client that if he wants to remove a property he should send me an empty string (but what about dates and other non-string types?)
The second option is actually a good option in my opinion. And that is also what we did (kind of).
I'm not sure if you can make the validation properties work with this option, but then again, should this validation not be on your domain layer? This could throw an exception from the domain which is handled by the rest layer and translated into a bad request.
This is how we did it in one application:
class PatchUserRequest {
private boolean containsName = false;
private String name;
private boolean containsEmail = false;
private String email;
@Length(max = 100) // haven't tested this, but annotation is allowed on method, thus should work
void setName(String name) {
this.containsName = true;
this.name = name;
}
boolean containsName() {
return containsName;
}
String getName() {
return name;
}
}
...
The json deserializer will instantiate the PatchUserRequest but it will only call the setter method for fields that are present. So the contains boolean for missing fields will remain false.
In another app we used the same principle but a little different. (I prefer this one)
class PatchUserRequest {
private static final String NAME_KEY = "name";
private Map<String, ?> fields = new HashMap<>();;
@Length(max = 100) // haven't tested this, but annotation is allowed on method, thus should work
void setName(String name) {
fields.put(NAME_KEY, name);
}
boolean containsName() {
return fields.containsKey(NAME_KEY);
}
String getName() {
return (String) fields.get(NAME_KEY);
}
}
...
You could also do the same by letting your PatchUserRequest extend Map.
Another option might be to write your own json deserializer, but I haven't tried that myself.
One could say that PATCH shouldn't be used in such example and I should use PUT to update my User.
I don't agree with this. I also use PATCH & PUT the same way as you stated:
- PUT - update object with its whole representation (replace)
- PATCH - update object with given fields only (update)