Best Practices for implementing APIs (on both client and server side)

[ePaul]

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:

• Be tolerant in processing and reading data of API responses, more specifically service clients must be prepared for compatible API extensions of response data:

  • Be tolerant with unknown fields in the payload (see also Fowler’s "TolerantReader" post), i.e. ignore new fields but do not eliminate them from payload if needed for subsequent PUT requests.

(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.)

[ePaul]

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.

[ePaul]

@a1exsh Given that you've written this already in the Java-docs, would you like to contribute this?

[a1exsh]

@a1exsh Given that you've written this already in the Java-docs, would you like to contribute this?

Sure! :)