Structural improvements: enhance headers handling

[arno-di-loreto]

Following (again) ideas from OAI/OpenAPI-Specification#563 and OAI/sig-moonwalk#115, extending OAI/OpenAPI-Specification#369:

• define reusable response headers (like parameters or definitions as proposed in OAI/OpenAPI-Specification#563 by @fehguy )
• set responses headers on each level: whole api, path, operation, responses (and response as stated in OAI/OpenAPI-Specification#369)

paths:
  responseHeaders:
     # Headers returned on all api responses
  /resources:
    responseHeaders:
      # Headers returned on all /resources operations responses
    get:
      responseHeaders:
        # Headers returned on all operations responses
      200:
         headers:
           # Headers returned on this response
schemas:
  responseHeaders:
    # reusable headers describe with a Header Object, used with $ref

The problem is the naming consistency: responseHeaders almost everywhere vs headers on response level. What if we use headers or responseHeaders everywhere?

nb: and don't forget to modify Header Object to include OAI/OpenAPI-Specification#321 (required)

[arno-di-loreto]

parent OAI/OpenAPI-Specification#560

[webron]

Can't put my finger on it, but something here seems tricky when it comes to the resolution of the 'effective' spec. Multiple levels of being able to define both headers and responses (which can define the headers as well)... feels like a recipe for trouble. I'm probably overthinking it though.

[etoews]

Being able to define reusable response headers in someway is a necessity. Having to constantly repeat yourself for response headers is a significant maintenance burden.

[talolierwork]

Sounds like a great idea, maybe even generalize it even more to use refer to definitions-like item from various places for reuse.

[iq-dot]

Absolutely a great idea and a must have.

Currently we hare facing issues where we have to copy paste headers across all APIs which makes for error prone updates and maintainability issues. The key flexibility would be able to reference the headers and in addition specifying headers at a global level would help clean up the spec.

[n-alex-white]

I agree, some means of defining standard headers to be applied to all the requests and responses in a swagger definition would be exceptionally useful. At the moment an API definition I'm working on has been bloated by 1,300 lines by the need to include the same additional headers for each response code on each API member.

it obscures the intent and provides maintenance problems; it is crying out for the ability to reference standard sets of headers IMO.

[synackSA]

I'm in the process of trying to define a API now and the thought of adding the rate-limit headers to every single response definition is already making me want to pack it in. This really needs to happen,.

[darrelmiller]

@synackSA Personally, I would define a 429 response in #/components/responses and reference it on whichever operations are rate limited.

I've never quite understood why APIs choose to return rate limiting headers on successful responses. Do client applications actually read those values and hold off on making requests until they know the reset period has ended? Is there some other function that makes them useful?

[JeanMertz]

Do client applications actually read those values and hold off on making requests until they know the reset period has ended? Is there some other function that makes them useful?

As a reference: our Jenkins setup has a feature where it "scrapes" our organisation's repositories and checks all branches for a valid Jenkinsfile. This plugin actually reads the X-Rate-Remaining value from the GitHub API and implements backoff functionality to spread out GitHub API requests to make sure it doesn't run out of requests before the limit is reset every hour.

Just wanted to chime in that apparently, there are valid use-cases for these headers 👍

[synackSA]

I'm personally not sure if will or won't but they can't blame us for not providing the information to them, it's up to them to actually implement it, either way, they will get rate limited if they it their limit. All the info is there for them to manage it otherwise.

[n-alex-white]

Four years on, are we any closer to getting response headers definable as components in the same way that request headers are?

Is there anything that can be done to help move this issue forwards somehow?

[handrews]

@n-alex-white It's possible to reference re-usable response headers under #/components/headers so I'm not sure what your question is. The larger issue here is setting headers at different levels, which is a much bigger change.

[Raimo33]

Almost 2025 and not even with OpenAPI3.1 we have the possibility of creating general response headers (for multiple response codes)

Big maintainability issue still!