Closed ePaul closed 4 months ago
Idea: add a section in the "Best Practices" appendix, which has some language-independent text and a short summary for how to do this with Java/Jackson, inspired by internal PR. We should link that both from rule 108 and the "Prefer to use PUT" part in the PATCH rule.
@a1exsh Given that you've written this already in the Java-docs, would you like to contribute this?
@a1exsh Given that you've written this already in the Java-docs, would you like to contribute this?
Sure! :)
Background During today's meeting, we discussed an issue that can happen with compatible API changes, when the client doesn't follow our guidelines strictly. Specifically, if a client does an update via a GET / edit / PUT sequence, if implemented naively (by ignoring unknown fields after GET), data in fields unknown to the client will get lost.
Our guidelines in rule 108 already cover this case, though only mentioned in a sub-clause:
(Highlight by me.)
Problem
We don't give any guidance on how to implement this, and we suspect that many clients in fact do not implement it this way. The naive way of implementing it would map the JSON object from the GET to a domain object (e.g. a Java POJO), then apply the edits on that domain object, then map the domain object back to a JSON object for sending it via PUT.
Suggested solution
We have a section with best practices and examples for how to implement specific use cases in various programming languages (optimally covering all ones on ADOPT in our tech radar, but let's start with e.g. Java.)