Add support for defining rate limits

[jugaadi]

Since API Rate limits just like AuthN also come under the API contract, it would be beneficial for a developer to define it in the API description itself. Most API vendors use different strategies for limiting excessing API usage. Therefore, a provision to define the strategy/scheme and the rate limits per operation(or at content-type level) would be really helpful. This would also help clients(generated or otherwise) to consume resources efficiently.

[karelhusa]

@jugaadi, what kind of information would you like to capture for rate limits?

Rate limits are often set to a particular category of consumers, i.e., a basic subscription may consume 100/day, whereas a gold subscription is allowed to consume 10.000/day.

There is an API and additionally different service levels for the API. Adding rate limits is adding service level into the API contract.

Would you like to add different service levels for the API or per operation?

[jugaadi]

We can add a keyword for defining rate limits per operation. Service level handling can be resolved via overlays.

[ralfhandl]

RateLimit header fields for HTTP allow conveying rate limits at runtime, and make the OpenAPI description independent of the user's (employer's) current subscription / service plan / ...

[jugaadi]

Aren't both consumed at different stages? I think both are relevant and the above headers can be used to define the limits in the document itself.

However, I'm not quite sure about the current adoption of these headers and therefore, unsure whether it needs to be part of the spec keywords or just data. Can be modelled as both(Content-Type) too.

Tagging the experts cc: @darrelmiller @earth2marsh @MikeRalphson

[MikeRalphson]

See the SLA4OAI extension work. Especially the ratesObject

[earth2marsh]

I consider rate limits to be a non-functional entitlement that is more aligned with the social contract than the technical contract. Some of your API customers may have access to APIs (functionality) that aren't available to everyone (like an API restricted to trusted partners), and that would require documentation of those distinct technical contracts/entitlements.

But if the functional contract is identical yet the usage limits/quotas vary by user, should the OpenAPI document reflect those various non-functional entitlements? It gets too complicated to couple the social contract into the technical contract, IMO.