Improve description of current API rate-limiting landscape.

[ioggstream]

I expect

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

[ioggstream]

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

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

• [x] Red Hat 3scale
• [x] Kong
• [x] Envoy proxy
• [x] Armeria Java API framework
• [x] express-rate-limit
• [x] pipedrive

Support via configuration from:

• Azure API Gateway exposes functionalities to implement this IBM api gateway
• datadog
• ensembl genomic browser api
• the hub controller

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

[fterpstra]

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

[bungle]

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!

[ioggstream]

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

Kudos to the Kong Team!

[bungle]

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

[ioggstream]

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

[ioggstream]

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