Replacing API documentation is not desirable

[Acconut]

Draft -08 mentions the following goal:

Documentation: Simplify API documentation by eliminating the need to include detailed quota limits and related fields in API documentation.

I am not sure how to understand this sentence. Does it suggest that API documentation about rate limit policies can be removed if the API implements rate limit headers? That does not sound desirable to me. I see the ratelimit header as an addition to API documentation, not a replacement. API documentation should include information about ratelimit policies, so I can plan accordingly before stating to integrate with said API. If ratelimit headers replace ratelimit documentation, I have to start sending API request before discovering the ratelimit policies.

Or does the sentence suggest that API documentation about proprietary rate limit headers (not the policies themselves) can removed because the documentation can just point to this specification? That seems acceptable.

Maybe the goal can be restated to clarify its intention.

[Kevsy]

My take: rate limits could be considered part of the business contract rather than the specification. e.g. a developer logging into a dashboard may read their rate limit there, and it could be tiered based on their level of access.

So I can see why a rate limit may not be suitable for the API definition document...but I think it would still be valuable to appear in the developer dashboard for each API. That said, the dashboard could point to the RateLimit response field as a canonical source, especially if RateLimits are dynamic (e.g. based on overall load on the API server as well as per-developer quota)

[ioggstream]

Does it suggest that API documentation about rate limit policies can be removed if the API implements rate limit headers?
That does not sound desirable to me.

This is not a recommendation, just a provider's choice. Prosaic ratelimit description only works with static limits.

A provider implementing this I-D is free to provide a static, prosaic ratelimit documentation or not.

the dashboard could point to the RateLimit response field as a canonical source, especially if RateLimits are dynamic

Exactly.