From 7854a17f068218edbf1d38137be70bc3b7e1acf2 Mon Sep 17 00:00:00 2001 From: tkrop Date: Tue, 18 Apr 2023 15:59:56 +0200 Subject: [PATCH] feat: improve headers --- models/request-headers-1.0.0.yaml | 118 ++++++++++++++++++++++------- models/response-headers-1.0.0.yaml | 72 ++++++++++++------ 2 files changed, 137 insertions(+), 53 deletions(-) diff --git a/models/request-headers-1.0.0.yaml b/models/request-headers-1.0.0.yaml index dec2ef39f..0b4c0edbb 100644 --- a/models/request-headers-1.0.0.yaml +++ b/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,23 +62,26 @@ 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 @@ -34,10 +89,12 @@ X-Tenant-ID: 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 @@ -45,11 +102,13 @@ X-Sales-Channel: 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 @@ -57,10 +116,11 @@ X-Frontend-Type: 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. + 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 @@ -68,10 +128,12 @@ X-device-Type: 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. + 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 diff --git a/models/response-headers-1.0.0.yaml b/models/response-headers-1.0.0.yaml index 3c7ab20d6..ab25526e3 100644 --- a/models/response-headers-1.0.0.yaml +++ b/models/response-headers-1.0.0.yaml @@ -1,18 +1,21 @@ -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" @@ -20,13 +23,16 @@ Cache-Control: 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" \ No newline at end of file + 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