Merge branch 'zalando:main' into main

zepdev · Apr 8, 2024 · fc6f5af · fc6f5af
2 parents 57d3d26 + d650980
commit fc6f5af
Show file tree

Hide file tree

Showing 6 changed files with 35 additions and 1 deletion.
diff --git a/chapters/best-practices.adoc b/chapters/best-practices.adoc
@@ -322,3 +322,25 @@ later than the given date:
 === Conclusion
 We suggest to either use the _{ETag} in result entities_ or _{Last-Modified}
 / {If-Unmodified-Since}_ approach.
+
+
+[[handling-compatible-extensions]]
+== Handling compatible API extensions
+
+[[client-handling-compatible-extensions]]
+=== In the clients
+
+Client must not eliminate unknown optional fields from the 
+fetched resource payload, and to serialize them later when submitting the
+complete resource payload back to the API server via {PUT} (<<108>>).
+
+When using Java with Jackson serialization, for example, that can be achieved
+by including a field in the Java class representing the API resource, like the
+following one:
+
+[source,java]
+----
+@JsonAnyGetter
+@JsonAnySetter
+private Map<String, JsonNode> additionalProperties = new HashMap<>();
+----
diff --git a/chapters/compatibility.adoc b/chapters/compatibility.adoc
@@ -133,6 +133,7 @@ Service clients should apply the robustness principle:
 ** Follow the redirect when the server returns HTTP status code {301} (Moved
   Permanently).
 
+The <<handling-compatible-extensions>> section describes a best practice to implement the requirements in Java. 
 
 [#111]
 == {MUST} treat OpenAPI specification as open for extension by default

diff --git a/chapters/http-requests.adoc b/chapters/http-requests.adoc
@@ -193,6 +193,9 @@ suggest to choose one and only one of the following patterns per endpoint
 
 1. Use {PUT} with complete objects to update a resource as long as feasible
    (i.e. do not use {PATCH} at all).
+   *Note:* this choice by the API server imposes additional requirements on
+   the client (<<108>>) which can be implemented e.g. in Java following the 
+   practice <<handling-compatible-extensions>>.
 2. Use {PATCH} with {RFC-7396}[JSON Merge Patch] standard, a
    specialized media type `application/merge-patch+json` for partial
    resource representation to update parts of resource objects.

diff --git a/chapters/introduction.adoc b/chapters/introduction.adoc
@@ -4,7 +4,7 @@
 Zalando’s software architecture centers around decoupled microservices
 that provide functionality via RESTful APIs with a JSON payload. Small
 engineering teams own, deploy and operate these microservices in their
-AWS (team) accounts. Our APIs most purely express what our systems do,
+AWS (team) accounts. Our APIs express most purely what our systems do,
 and are therefore highly valuable business assets. Designing
 high-quality, long-lasting APIs has become even more critical for us
 since we started developing our new open platform strategy, which

diff --git a/models/request-headers-1.0.0.yaml b/models/request-headers-1.0.0.yaml
@@ -1,3 +1,7 @@
+# This document is DEPRECATED and only maintained for backward compatibility.
+# Separation of request vs. response header definition is partially redundant and not needed. 
+# Instead, please use the HEADER DEFINITIONS provided in headers-<version>.yaml
+
 # Standard Headers
 
 If-Match:

diff --git a/models/response-headers-1.0.0.yaml b/models/response-headers-1.0.0.yaml
@@ -1,3 +1,7 @@
+# This document is DEPRECATED and only maintained for backward compatibility.
+# Separation of request vs. response header definition is partially redundant and not needed. 
+# Instead, please use the HEADER DEFINITIONS provided in headers-<version>.yaml
+
 # Standard Headers
 
 Cache-Control: