feat: improve headers guideline (#769)

Author: tkrop

.gitignore

@@ -1,6 +1,7 @@
 .project
 .sass-cache/
 output/
+includes/
 .project
 .idea
 .metals

BUILD.adoc

@@ -27,6 +27,15 @@ to the `all`-target.
 **Note:** We have currently not tested the capability of `markdownlint` (or
 `make format`) to fix linter violations.
 
+== Find next Rule ID
+
+If you want to create a new rule, you need to define a new rule identifier. Use
+the following command to find the next unused rule identifier.
+
+[source,bash]
+----
+make next-rule-id
+----
 
 == Generate Custom CSS
 

Makefile

@@ -4,6 +4,7 @@ DIRMOUNTS := /documents
 DIRCONTENTS := chapters
 DIRSCRIPTS := scripts
 DIRBUILDS := output
+DIRINCLUDES := includes
 DIRWORK := $(shell pwd -P)
 
 .PHONY: all clean install lint format pull assets rules html pdf epub force
@@ -12,7 +13,7 @@ DIRWORK := $(shell pwd -P)
 
 all: clean html rules
 clean:
-	rm -rf $(DIRBUILDS);
+	rm -rf $(DIRBUILDS) $(DIRINCLUDES);
 
 install: $(NVM_BIN)/markdownlint
 $(NVM_BIN)/markdownlint:
@@ -58,20 +59,23 @@ rules: check-rules
 	$(DIRSCRIPTS)/generate-rules-json.sh  | \
 	  jq -s '{rules: . | sort}' | tee $(DIRBUILDS)/rules >$(DIRBUILDS)/rules.json;
 
-html: check assets pull
+$(DIRINCLUDES): models/headers-1.0.0.yaml $(DIRSCRIPTS)/generate-includes.sh
+	mkdir -p $(DIRINCLUDES); $(DIRSCRIPTS)/generate-includes.sh "$(DIRINCLUDES)";
+
+html: $(DIRINCLUDES) check assets pull
 	docker run -v $(DIRWORK):$(DIRMOUNTS)/ ${DOCKER} asciidoctor \
 	  -D $(DIRMOUNTS)/$(DIRBUILDS) index.adoc;
 
 # Not used any longer.
-pdf: check pull
+pdf: $(DIRINCLUDES) check pull
 	docker run -v $(DIRWORK):$(DIRMOUNTS)/ ${DOCKER} asciidoctor-pdf -v \
 		-a pdf-fontsdir=$(DIRMOUNTS)/resources/fonts \
 		-a pdf-theme=$(DIRMOUNTS)/resources/themes/pdf-theme.yml \
 	  -D $(DIRMOUNTS)/$(DIRBUILDS) index.adoc;
 	mv -f $(DIRBUILDS)/index.pdf $(DIRBUILDS)/zalando-guidelines.pdf;
 
 # Not used any longer.
-epub: check pull
+epub: $(DIRINCLUDES) check pull
 	docker run -v $(DIRWORK):$(DIRMOUNTS)/ ${DOCKER} asciidoctor-epub3 \
 	  -D $(DIRMOUNTS)/$(DIRBUILDS) index.adoc;
 	mv -f $(DIRBUILDS)/index.epub $(DIRBUILDS)/zalando-guidelines.epub;

README.adoc

@@ -4,8 +4,6 @@
 https://github.com/zalando/restful-api-guidelines/actions/[image:https://github.com/zalando/restful-api-guidelines/actions/workflows/build.yml/badge.svg[Build status]]
 Latest published version:
 http://zalando.github.io/restful-api-guidelines/[*HTML*],
-http://zalando.github.io/restful-api-guidelines/zalando-guidelines.pdf[*PDF*],
-http://zalando.github.io/restful-api-guidelines/zalando-guidelines.epub[*EPUB3*]
 
 == Purpose
 

chapters/compatibility.adoc

@@ -87,7 +87,7 @@ and be explicit in what is supported:
 * Ignoring unknown input fields is actually not an option for {PUT}, since it
   becomes asymmetric with subsequent {GET} response and HTTP is clear about the
   {PUT} _replace_ semantics and default roundtrip expectations (see
-  {RFC-7231}#section-4.3.4[RFC 7231 Section 4.3.4]). Note, accepting (i.e. not
+  {RFC-9110}#section-9.3.4[RFC 9110 Section 9.3.4]). Note, accepting (i.e. not
   ignoring) unknown input fields and returning it in subsequent {GET} responses
   is a different situation and compliant to {PUT} semantics.
 * Certain client errors cannot be recognized by servers, e.g. attribute name
@@ -126,7 +126,7 @@ Service clients should apply the robustness principle:
 ** Be prepared to handle HTTP status codes not explicitly specified in endpoint
   definitions. Note also, that status codes are extensible. Default handling is
   how you would treat the corresponding {x00} code (see
-  {RFC-7231}#section-6[RFC 7231 Section 6]).
+  {RFC-9110}#section-15[RFC 9110 Section 15]).
 ** Follow the redirect when the server returns HTTP status code {301} (Moved
   Permanently).
 

chapters/deprecation.adoc

@@ -62,8 +62,8 @@ breaking effects on ongoing consumers. See also <<193>>.
 
 During the deprecation phase, the producer should add a `Deprecation: <date-time>`
 (see https://tools.ietf.org/html/draft-ietf-httpapi-deprecation-header[draft: RFC
-Deprecation HTTP Header]) and - if also planned - a `Sunset: <date-time>` (see
-{RFC-8594}#section-3[RFC 8594]) header on each response affected by a
+Deprecation HTTP Header Field]) and - if also planned - a `Sunset: <date-time>`
+(see {RFC-8594}#section-3[RFC 8594]) header on each response affected by a
 deprecated element (see <<187>>).
 
 The {Deprecation} header can either be set to `true` - if a feature is retired
@@ -81,17 +81,35 @@ Sunset: Wed, 31 Dec 2025 23:59:59 GMT
 
 If multiple elements are deprecated the {Deprecation} and {Sunset} headers are
 expected to be set to the earliest time stamp to reflect the shortest interval
-consumers are expected to get active.
+at which consumers are expected to get active. The {Deprecation} and {Sunset}
+headers can be defined as follows in the API specification (see also the
+default definition below):
+
+[source,yaml]
+----
+components:
+  parameters|headers:
+    Deprecation:
+      $ref: 'https://opensource.zalando.com/restful-api-guidelines/models/headers-1.0.0.yaml#/Deprecation'
+    Sunset:
+      $ref: 'https://opensource.zalando.com/restful-api-guidelines/models/headers-1.0.0.yaml#/Sunset'
+----
+
+[source,yaml]
+----
+include::../includes/deprecation.yaml[]
+include::../includes/sunset.yaml[lines=3..-1]
+----
 
 *Note:* adding the {Deprecation} and {Sunset} header is not sufficient to gain
 client consent to shut down an API or feature.
 
-*Hint:* In earlier guideline versions, we used the `Warning` header to provide
-the deprecation info to clients. However, `Warning` header has a less specific
+*Hint:* In earlier guideline versions, we used the {Warning} header to provide
+the deprecation info to clients. However, {Warning} header has a less specific
 semantics, will be obsolete with
 https://tools.ietf.org/html/draft-ietf-httpbis-cache-06[draft: RFC HTTP
-Caching], and our syntax was not compliant with {RFC-7234}#page-29[RFC 7234
--- Warning header].
+Caching], and our syntax was not compliant with {RFC-9111}#section-5.5[RFC 9111
+ Section 5.5 "Warning"].
 
 
 [#190]
@@ -105,6 +123,7 @@ ensure alignment with service owners on required migration task.
 *Hint:* In earlier guideline versions, we used the `Warning` header to provide
 the deprecation info (see hint in <<189>>).
 
+
 [#191]
 == {MUST} not start using deprecated APIs