alt Hacker NewsLooking at the rfc, I'm not sure I understand the motivation, as it suggests multiple times that a client or intermediary will have to read external documentation:
> Servers MAY choose to return partition keys that distinguish between quota allocated to different consumers or different resources. There are a wide range of strategies for partitioning server capacity, including per user, per application, per HTTP method, per resource, or some combination of those values. The server SHOULD document how the partition key is generated so that clients can predict the key value for a future request and determine if there is sufficient quota remaining to execute the request.
If external documentation is required, why send the header? It seems as though having it in the documentation is generally preferable, rather than something to avoid.
The relevant word here is MAY[1]
It's true that if an API requires the devs of its consumers to have consulted documentation in order to respect the RateLimit header, they can just as easily include custom API logic for traffic control, but this does provide a nice standardized way to do so nevertheless.
And since the word is "MAY", APIs may also use standard responses that don't require an custom handling. As an example a CLI-builder library which parses OpenAPI spec can adopt changes to handle the RateLimit header automatically, in the situations where consulting docs is not required.
[1] https://datatracker.ietf.org/doc/html/rfc2119