Merge pull request #760 from zalando/improve-headers

feat: improve headers

models/request-headers-1.0.0.yaml

@@ -1,7 +1,59 @@
+# Standard Headers
+
+If-Match:
+  name: If-Match
+  in: header
+  required: false
+  description: |-
+    The `If-Match` header field is used to declare a list of identifiers that
+    are required to match the current resource version identifier in at least
+    one position as a pre-condition for executing the request on the server
+    side. This behavior is used to validate and reject optimistic updates, by
+    checking if the resource version a consumer has based his changes on is
+    outdated on arrival of the change request to prevent lost updates.
+
+    If the pre-condition fails the server will respond with status code `412`
+    (Precondition Failed). For further details see [RFC 7232 Section
+    3.1](https://tools.ietf.org/html/rfc7232#section-3.1).
+  schema:
+    type: array
+    items:
+      type: string
+  style: simple
+  explode: false
+  example: W/"xy", "5", "5db68c06-1a68-11e9-8341-68f728c1ba70"
+
+If-None-Match:
+  name: If-None-Match
+  in: header
+  required: false
+  description: |-
+    The `If-None-Match header` field is used to declare a list of identifiers
+    that are required to fail matching all the current resource version
+    identifiers as a pre-condition for executing the request on the server
+    side. This is especially used in conjunction with an `*` (asterix) that is
+    matching all possible resource identifiers to ensure the initial creation
+    of a resource. Other use cases are possible but rare.
+
+    If the pre-condition fails the server will respond with status code `412`
+    (Precondition Failed). For further details see [RFC 7232 Section
+    3.2](https://tools.ietf.org/html/rfc7232#section-3.2) for further details.
+  schema:
+    type: array
+    items:
+      type: string
+  style: simple
+  explode: false
+  example: W/"xy", "5", "5db68c06-1a68-11e9-8341-68f728c1ba70"
+
+# Custom Headers
+
 X-Flow-ID:
   name: X-Flow-ID
-  description: |
-      A custom header that will be passed onto any further requests and can be used for investigation in error cases.
+  description: |-
+    The `X-Flow-ID` is a custom header containing a unique flow identifier that
+    that must be passed to any further request. It can be used to investigate
+    request related log entries end events.
   in: header
   schema:
     type: string
@@ -10,68 +62,84 @@ X-Flow-ID:
 X-Mobile-Advertising-ID:
   in: header
   name: X-Mobile-Advertising-ID
-  description: >
-    It is a unique, customer-resettable identifier provided by mobile device’s operating system to facilitate
-    personalized advertising, and usually passed by mobile apps via http header when calling backend services.
+  description: |-
+    A unique, customer-resettable identifier provided by the operating system of
+    a mobile device to facilitate personalized advertising, and usually passed
+    by mobile apps via header when calling backend services.
+
     It is either the [IDFA](https://developer.apple.com/documentation/adsupport/asidentifiermanager)
     (Apple Identifier for mobile Advertising) for iOS, or the
-    [GAID](https://support.google.com/googleplay/android-developer/answer/6048248) (Google mobile Advertising Identifier)
-     for Android.
+    [GAID](https://support.google.com/googleplay/android-developer/answer/6048248)
+    (Google mobile Advertising Identifier) for Android.
   schema:
     type: string
     example: cdda802e-fb9c-47ad-0794d394c912
 
 X-Tenant-ID:
   name: X-Tenant-ID
-  description: |
-    Identifies the tenant initiated the request to the multi tenant Zalando Platform. The X-Tenant-ID must be set
-     according to the Business Partner ID extracted from the OAuth token when a request from a Business Partner
-     hits the Zalando Platform.
+  description: |-
+    The unique identifier of the tenant that initiated the request to the
+    multi-tenant Zalando Platform. The X-Tenant-ID is set to the ID of the
+    business partner extracted from the `OAuth`-token of the request. The
+    `X-Tenant-ID` should be passed-through as generic aspect.
   in: header
   schema:
     type: string
     example: 9f8b3ca3-4be5-436c-a847-9cd55460c495
 
 X-Sales-Channel:
   name: X-Sales-Channel
-  description: |
-    Sales channels are owned by retailers and represent a specific consumer segment being addressed with a
-    specific product assortment that is offered via CFA retailer catalogs to consumers (see fashion platform
-    glossary (internal link))
+  description: |-
+    Unique identifier of the sales channel related to the request. Sales
+    channels are owned by retailers and represent a specific consumer segment
+    being addressed with a specific product assortment that is offered via the
+    CFA retailer catalogs to consumers (see fashion platform glossary). The
+    `X-Sales-Channel` should be passed-through as generic aspect.
   in: header
   schema:
     type: string
     example: 52b96501-0f8d-43e7-82aa-8a96fab134d7
 
 X-Frontend-Type:
   name: X-Frontend-Type
-  description: |
-    Consumer facing applications (CFAs) provide business experience to their customers via different
-    frontend application types, for instance, mobile app or browser. Info should be passed-through as
-    generic aspect — there are diverse concerns, e.g. pushing mobiles with specific coupons, that make use
-    of it. Current range is mobile-app, browser, facebook-app, chat-app, email.
+  description: |-
+    The type of the consumer facing application (CFA) used to initiate the
+    request. CFAs provide business experience to their customers via different
+    frontend application types, `mobile-app`, `browser`, `facebook-app`,
+    `chat-app`, and `email`. The `X-Frontend-Type` should be passed-through as
+    generic aspect - there are diverse concerns, e.g. pushing mobiles with
+    specific coupons, that make use of it.
   in: header
   schema:
     type: string
     example: mobile-app
 
 X-device-Type:
-  name: X-device-Type
-  description: |
-    There are also use cases for steering customer experience (incl. features and content) depending on
-    device type. Via this header info should be passed-through as generic aspect. Current range is
-    smartphone, tablet, desktop, other.
+  $ref: 'https://opensource.zalando.com/restful-api-guidelines/models/request-headers-1.0.0.yaml#/X-Device-Type'
+
+X-Device-Type:
+  name: X-Device-Type
+  description: |-
+    The device type used to initiate the request. There are also use cases
+    for steering customer experience (incl. features and content) depending on
+    device types, e.g. `smartphone`, `tablet`, `desktop`, and `other`. The
+    `X-Device-Type` should be passed-through as generic aspect.
   in: header
   schema:
     type: string
     example: tablet
 
 X-device-OS:
-  name: X-device-OS
-  description: |
-    On top of device type above, we even want to differ between device platform, e.g. smartphone
-    Android vs. iOS. Via this header info should be passed-through as generic aspect.
-    Current range is iOS, Android, Windows, Linux, MacOS.
+  $ref: 'https://opensource.zalando.com/restful-api-guidelines/models/request-headers-1.0.0.yaml#/X-Device-OS'
+
+X-Device-OS:
+  name: X-Device-OS
+  description: |-
+    The operating system used by the device initiating the request. On top of
+    device type, we want to differ between device platforms, e.g. between
+    computers, smartphone and tablets with `iOS`, `Android`, `Windows`,
+    `Linux`, and `MacOS`. The `X-Device-OS` should be passed-through as generic
+    aspect.
   in: header
   schema:
     type: string

models/response-headers-1.0.0.yaml

@@ -1,32 +1,38 @@
-X-Flow-ID:
-  name: X-Flow-ID
-  description: |
-      A custom header that will be passed onto any further requests and can be used for investigation in error cases.
-  in: header
-  schema:
-    type: string
-    example: GKY7oDhpSiKY_gAAAABZ_A
+# Standard Headers
 
 Cache-Control:
   in: header
   name: Cache-Control
-  description: >
-    The RFC 7234 Cache-Control header field is providing directives to control how proxies and clients are
-    allowed to cache responses results for performance.
+  description: |
+    The `Cache-Control` header field is providing directives to control how
+    proxies and clients are allowed to cache responses results for performance.
+    Clients and proxies are free to not support caching of results, however if
+    they do, they must obey all directives mentioned in [RFC-7234 Section
+    5.2.2](https://tools.ietf.org/html/rfc7234) to the word.
+
+    In case of caching, the directive provides the scope of the cache entry,
+    i.e. only for the original user (private) or shared between all users
+    (public), the lifetime of the cache entry in seconds (max-age), and the
+    strategy how to handle a stale cache entry (must-revalidate). Please note,
+    that the lifetime and validation directives for shared caches are different
+    (s-maxage, proxy-revalidate).
   schema:
     type: string
     example: "private, must-revalidate, max-age=3600"
 
 Vary:
   in: header
   name: Vary
-  description: >
-    The "Vary" header field in a response describes what parts of a
-    request message, aside from the method, Host header field, and
-    request target, might influence the origin server's process for
-    selecting and representing this response.  The value consists of
-    either a single asterisk ("*") or a list of header field names
-    (case-insensitive).
+  description: |
+    The `Vary` header field in the response describes which parts of the
+    request message, aside from the method, the `Host` header field, and the
+    request target path, might have influence the server in selecting the
+    presented response. A client or proxy that caches the response must respect
+    this information to ensure that it delivers the correct cache entry (see
+    [RFC-7231 Section 7.1.4](https://tools.ietf.org/html/rfc7231#section-7.1.4)).
+
+    The value consists of either a single asterisk (`*`) or a list of
+    case-insensitive header field names.
   schema:
     type: string
     example: "accept-encoding, accept-language"
@@ -35,12 +41,28 @@ ETag:
   in: header
   name: ETag
   description: >
-    The RFC 7232 ETag header field in a response provides the entity-tag of
-    a selected resource. The entity-tag is an opaque identifier for versions
-    and representations of the same resource over time, regardless whether
-    multiple versions are valid at the same time. An entity-tag consists of
-    an opaque quoted string, possibly prefixed by a weakness indicator (see
-    [RFC 7232 Section 2.3](https://tools.ietf.org/html/rfc7232#section-2.3).
+    The `ETag` header field in a response provides an opaque quoted string
+    identifying the distinct delivered resource. The same selected resource
+    depending on version and representation may be identified by multiple
+    identifiers. The `ETag` value is guaranteed to change whenever the
+    resource changes, and thereby enabling optimistic updates.
+
+    An identifier consists of an opaque quoted string, possibly prefixed by
+    a weakness indicator. For further details see [RFC 7232 Section
+    2.3](https://tools.ietf.org/html/rfc7232#section-2.3).
   schema:
     type: string
-    example: W/"xy", "5", "5db68c06-1a68-11e9-8341-68f728c1ba70"
+    example: W/"xy", "5", "5db68c06-1a68-11e9-8341-68f728c1ba70"
+
+# Custom Headers
+
+X-Flow-ID:
+  name: X-Flow-ID
+  description: |
+    The `X-Flow-ID` is a custom header containing a unique flow identifier that
+    was be passed to any further request. It can be used to investigate request
+    related log entries end events.
+  in: header
+  schema:
+    type: string
+    example: GKY7oDhpSiKY_gAAAABZ_A