draft-polli-ratelimit-headers Improve description of current API rate-limiting landscape.

I expect

The introduction on the current throttling landscape to be more comprehensive and detailed.

Jul 17 '19 13:07 ioggstream

Compliant implementations: Zalando, IBM, 3scale, Kong, Dutch government, pipedrive, Envoy

Explicit support via RateLimit-* or X-RateLimit-* from:

Support via configuration from:

Uses 429 and the triple like the following

x-ratelimit-limit: 5000
x-ratelimit-remaining: 50
x-ratelimit-reset: 10  # delta seconds

Can be implemented? Yes

Google

Returns 429 or 403 depending on the API.

Yelp

Returns 429

RateLimit-DailyLimit: 5000
RateLimit-Remaining: 4999
RateLimit-ResetTime: 2018-03-28T00:00:00+00:00

Considerations:

doesn't prefix headers with Yelp- see https://tools.ietf.org/html/rfc6648
uses RFC3339 which is fine but different from Retry-After, nice thing uses another header name
non clock-skew safe

Can be implemented with this spec? Yes, eg:

RateLimit-Limit: 5000,    5000; w=86400   # expliciting daily window in the optional comment part
RateLimit-Remaining: 4999
RateLimit-Reset: 36000                             # 10 hours before reset time

Amazon

Amazon uses custom headers with x-mws-quota-resetsOn using the IMF-fixdate syntax. The time-window is hourly.

x-mws-quota-max: 3600
x-mws-quota-remaining: 10
x-mws-quota-resetsOn: Wed, 06 Mar 2013 19:07:58 GMT

Can be implemented with this spec? Yes, switching to delta-seconds eg:

RateLimit-Limit: 3600, 3600;w=3600
RateLimiit-Remaining: 10
RateLimit-Reset: 1000

Github

Uses 429 and the triple like the following

x-ratelimit-limit: 5000
x-ratelimit-remaining: 50
x-ratelimit-reset: 1563525874  # unix timestamp

considerations:

non clock-skew safe
different from retry-after

Can be implemented with this spec? Yes, but should change the x-ratelimit-reset semantic

twitter, axway, oracle

https://developer.twitter.com/en/docs/basics/rate-limiting.html
axway
[oracle](https://docs.oracle.com/cd/E50612_01/doc.11122/user_guide/content/content_max_messages.html

Uses 429 and the triple like the following (same as github, but with different names)

x-rate-limit-limit: 5000
x-rate-limit-remaining: 50
x-rate-limit-reset: 1563525874  # unix timestamp

mulesoft

https://docs.mulesoft.com/api-manager/2.x/rate-limiting-and-throttling-sla-based-policies

Uses delta-seconds with milliseconds

x-ratelimit-limit: 5000
x-ratelimit-remaining: 50
x-ratelimit-reset: 12000  # milliseconds

Jul 19 '19 08:07 ioggstream

The Dutch government API strategy supports the IETF proposal. https://geonovum.github.io/KP-APIs/API-strategie-extensies/#rate-limiting we will add more detail in the near future

Dec 13 '19 09:12 fterpstra

Kong has now merged: https://github.com/Kong/kong/pull/5335

that implements:

RateLimit-Limit: <integer>
RateLimit-Remaining: <integer>
RateLimit-Reset: <integer>

First we thought about implementing multi-window info on RateLimit-Limit but it felt something that might change in future revision, and in general makes it harder to parse this header. We also found the syntax bit confusing (especially the , vs ;). Just a comment, has it ever been considered to add that as optional extra header, such as RateLimit-Window?

The feature will land on the upcoming Kong 2.0.0.

We will follow closely the work on this RFC and implement the possible changes in future revisions. Thank you for all this works, and the proposals to out project!

Dec 19 '19 09:12 bungle

@bungle great work! Is there an ETA for the 2.0.0?

Kudos to the Kong Team!

Dec 19 '19 13:12 ioggstream

@ioggstream I would expect final out on January. Release candidate is likely before Christmas :-).

Dec 19 '19 15:12 bungle

https://github.com/line/armeria Java API framework is implementing this spec. See https://github.com/line/armeria/blob/master/bucket4j/src/main/java/com/linecorp/armeria/common/throttling/ThrottlingHeaders.java#L24

Jun 24 '20 09:06 ioggstream

There's MERGED PR on EnvoyProxy https://github.com/envoyproxy/envoy/pull/12410

Aug 04 '20 18:08 ioggstream