Define headers dependencies

[ioggstream]

I expect

The spec to define header inter-dependencies and returning policies

Hypothesis

• [x] Limit -> Reset
• [x] Limit, Remaining, Reset

Note

Do I have to always return all headers? No Do I have to expose all headers or I can only expose a subset? Limit,Reset are REQUIRED, Remaining is OPTIONAL Do we need to add some considerations on client implementation? Already present.

[ioggstream]

• 28 clarifies that clients MUST NOT assume a server always returns fields

[ioggstream]

Comment by Erik.

In https://ietf-wg-httpapi.github.io/ratelimit-headers/draft-ietf-httpapi-ratelimit-headers.html#name-providing-ratelimit-fields

You state ‘A server MAY use one or more "RateLimit" response fields defined in this document to communicate its quota policies.’ but it does not clearly define how they would be used in isolation or how a client should respond to a limited set of headers (other than discussed earlier above)

My feeling is RateLimit-Limit can be optional and RateLimit-Remaining and RateLimit-Reset can be used as a pair. RateLimit-Reset would only have value in isolation if sent with a 429 response code, on other responses it would be meaningless.

[unleashed]

It could also make sense to return Reset with other 4XX status codes such as 401 and 403, so I think we don't really want to mandate a specific relation other than, at most, saying that unsuccessful requests (for a broad definition of those, possibly including 4XX and 5XX at a minimum) with this field are expected to be unsuccessful until that time elapses.

[ioggstream]

After a couple of years of adoption, my experience is the following:

1. implementations use all 3 fields. Though theoretically one could just return Remaining and Reset, I never found an implementation doing this :heavy_check_mark:

2. implementations don't know Remaining, and just return Limit and Reset with a fixed window (eg. 1 second).

RateLimit-Limit: 10
RateLimit-Reset: 1

We can then recommend the following:

Limit, Reset: MUST Remaining: SHOULD

Since https://ietf-wg-httpapi.github.io/ratelimit-headers/draft-ietf-httpapi-ratelimit-headers.html#section-1.1-4.6.1 I now think that we shouldn't mess with status codes.

@unleashed if this sounds reasonable to you, I can provide a PR

[unleashed]

Yes, it sounds good, thank you!