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.