Structural improvements: enhance headers handling

[arno-di-loreto]

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

• define reusable response headers (like parameters or definitions as proposed in Add default responses #563 by @fehguy )
• set responses headers on each level: whole api, path, operation, responses (and response as stated in Share header with multiple response objects #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 #321 (required)

[arno-di-loreto]

parent #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!

[TamSzaGot]

A well needed feature indeed.

[handrews]

This seems like something for which the now-released Overlay Specification might be the best solution?

[handrews]

@OAI/tsc this sort of "set a global thing to apply everywhere" feels like it's best addressed by the now-published Overlay Specification. Do we want to make that official and close this enhancement in favor of Overlays?

[mikekistler]

@handrews Maybe. But I think there's a counter-argument worth considering.

The counter-argument is that some people will want the API description to be complete on its own -- not require an Overlay to "fix it up". Saying that you must use Overlays for this kind of thing just makes it harder for API description authors and API description users.

An alternative approach is to borrow some of the ideas from the Overlays spec. By that I mean that we could include an "actions" field in the OAS that would work very much like the actions in Overlays. This reuses concepts and possibly technology that is already built but makes it directly available in OAS.

[handrews]

@mikekistler I could see having an overlays field in the OpenAPI Object that would let you name sets of overlays to apply, which could be inline or referenced 🤔 (just speculating here, don't take it too seriously!)

I'll put this in 3.3 for further consideration, as I suspect there would be too much to work out for the super-quick 3.2 plan.