Add X-RateLimit-* headers

[ioggstream]

I wish

apicast supports returing those 3 headers after every call:

• X-RateLimit-Limit maximum requests limit configured for the API endpoint
• X-RateLimit-Remaining remaining requests for the API endpoint until next counter reset
• X-RateLimit-Reset remaining seconds until next counter reset (same as Retry-After)

Steps To Reproduce

1. I invoke a throttled API

Current Result

2. I get no throttling headers

Expected Result

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 58 

Notes

See https://issues.redhat.com/browse/THREESCALE-3795

[davidor]

In the latest version (3.4.0) we introduced one of those headers: #929

When rate-limited by the 3scale backend, APIcast returns the number of seconds that the caller needs to wait before it's authorized again in the "Retry-After" header.

Returning something like X-RateLimit-Limit and X-RateLimit-Remaining is complicated because of how mapping rules and metrics work in the 3scale model. The main reason is that different endpoints might increase the same metric.

Imagine a set of mapping rules like this one:
/some_path => metric_m1 + 1
/another_path => metric_m1 + 2

When the caller hits /some_path, APIcast could return the number of remaining metric_m1s, but that remaining would become invalid once the caller hits another_path.

[ioggstream]

Hi @davidor, and thanks for your reply!

Forewords: various countries are introducing API frameworks requiring (esp. for payment/revenue govt APIs) specific throttling headers (links below).

iiuc mismatches are related to configurations where different endpoints increase the same metric, but probably there was a similar issue with Retry-After.

Reading https://github.com/3scale/apicast/pull/929/files#diff-31313c92616b54028dac1ba183e6f79aR359 it seems that similar values are exposed via 3scale-limit-reset (would be great to have a customizable name for that header).

I can even try to provide PRs & co once we agree on the subject.

Thanks for your time,
R.

Links

• Italian rules, in English
• a gov.uk API docs
• Netherland ongoing work on standards

[davidor]

Hi @ioggstream ,

The problem does not apply to the Retry-After header, because the 3scale backend takes all the metrics affected into account.

I'd be open to adding the "limit" and "remaining" headers, but I think they should be opt-in, because of the problems I mentioned above.

I think that with the 3scale model it is very common to have several endpoints that increment the same metric. It's important to take into account "parent metrics" as well. When increasing the child metric the parent gets increased by the same value.

So imagine that we have two metrics "m1" and "m2", and both of them are children of "Hits", in that case, if we define a limit on "Hits" the information in the "limit" and "remaining" headers might not be accurate for a set of rules like the following one:

/some_path => m1 + 1
/another_path => m2 + 1

[ioggstream]

Hi @davidor, and thanks for your reply!

I'd be open to adding the "limit" and "remaining" headers, but I think they should be opt-in, because of the problems I mentioned above.

Sure! We will document it.

When increasing the child metric the parent gets increased by the same value.

Ok, so depending from the api path you could be throttled out or not. In any case
the API provider knows its logic and can easily balance its policy.

[ioggstream]

Hi @davidor,

I'm writing this draft-rfc on the subject. Let me know if that can help
in developing this task.

https://ioggstream.github.io/draft-polli-ratelimit-headers/draft-polli-ratelimit-headers.html

[ioggstream]

@unleashed do you confirm we can close this via #1166?

[eloycoto]

Yep, thanks