Add OpenAPI models for headers

[vadeg]

API guideline contains complete data models for Money and Problem objects. Also it has Address object description but API designers can not reference it in their APIs.

I would like to suggest to extend predefined models to headers. Developer can reference header object from API like it happened with data models mentioned above.

Example

Suppose there are ready to use models for Accept-Language and X-Mobile-Advertising-ID headers available at https://opensource.zalando.com/restful-api-guidelines/headers/schema.yaml.

Accept-Language

Accept-Language:
      in: header
      name: Accept-Language
      description: > 
        The header advertises which languages the client is able to understand, and which locale variant is preferred. (By languages, we mean natural languages, such as English, and not programming languages.) 
      schema:
        type: string
        example: "fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5"       

X-Mobile-Advertising-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 faciliate personalized advertising, and usually passed by mobile apps via http 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.
  schema:
    type: string
    example: cdda802e-fb9c-47ad-0794d394c912

Developer, instead of describing headers, can reference them in the API definition like this:

openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0 
paths:
  /test:
    get:
      parameters:
      - $ref: "https://opensource.zalando.com/restful-api-guidelines/headers/schema.yaml#/X-Mobile-Advertising-ID"
      - $ref: "https://opensource.zalando.com/restful-api-guidelines/headers/schema.yaml#/Accept-Language"
      responses:
        200:
          description: Some response
          headers:
            X-Mobile-Advertising-ID:
              $ref: "https://opensource.zalando.com/restful-api-guidelines/headers/schema.yaml#/X-Mobile-Advertising-ID"
          content:
            application/json:
              schema:
                type: string
                example: Response object

Limitations

There is a limitation exist - OpenAPI doesn't allow to define header once and reuse it in parameters section for path and in headers section in response. We have to maintain separate schemas for request parameters and response parameters, e.g. https://opensource.zalando.com/restful-api-guidelines/request-headers/schema.yaml#/request-headers for request headers and https://opensource.zalando.com/restful-api-guidelines/request-headers/schema.yaml#/response-headers for response headers.

[ePaul]

From the meeting

• we generally only want this for headers where the guidelines talks about them
• we start with the proprietary headers (and include the example on how to use it in the table of proprietary headers in rule 183).
• other headers can be added later when we see a need for it.

For request headers, we create predefined parameters of type header, for response headers we define it as header object.

@gewald will start with this, and coordinate with @tkrop and @vadeg to not cause duplicate work.

[tfrauenstein]

@gewald Hi Gerd, you volunteered for ownership of this issue -- when we can expect progress? Thank you!

[ePaul]

One open issue from the PR:

@tkrop suggested:

@gewald thanks great contribution. Only one note, the structural similarity between response and request headers suggests that we join both in common file and thereby simplify referencing - if possible.

It was decided back then to not delay merging the PR.

We just now (in the guild meeting) decided that this is not a serious enough issue to keep this open.