How to specify quotas and rates for all operations?
timburks opened this issue · comments
As I read the spec, it appears that quotas and rates are always specified with metrics that are placed under specific paths and operations. I think this might be burdensome for large APIs, particularly when limits are expected to be the same for all operations. Is there a way to specify quotas and rates for all operations or for specified subsets of operations in an API?
Unfortunately, currently it is not supported such a mechanism and, therefore, you should repeat the same limits specifications for all the different paths. Nevertheless, I definitively think it could be great to have some sort of "syntax sugar" to avoid that repetition; perhaps to have some keyword like "global" to replace the path and define global limits. We can discuss this issue in the next TC Meeting that is held next Thursday and boost a pull request to include it in the spec.
If you're using YAML, you could use its anchors and aliases.
That is quite interesting @theganyo . Could you provide an example on how you would apply such a mechanism in an example of SLA4OAI?
Sure. Here's the sample from the spec that I rewrote to use the same rate for each request as an example:
context:
id: petstore-sample
type: plans
api:
$ref: ./petstore-service.yml
provider: ISAGroup
metrics:
requests:
type: "int64"
description: "Number of requests"
plans:
base:
availability: R/00:00:00Z/23:00:00Z
free:
rates:
/pets/{id}:
get: &one-per-second
requests:
- max: 1
period: secondly
quotas:
/pets:
post: *one-per-second
pro:
pricing:
cost: 5
currency: EUR
billing: monthly
rates:
/pets/{id}:
get: *one-per-second
You obviously can't set globals without changing the spec, but YAML does allow you to define and reuse chunks anywhere like this. That said, this is only YAML - JSON doesn't support this, so it may still be desirable to include more formal references within the spec itself as OpenAPI does.
@theganyo Thanks for that! Do you know how well it is supported by YAML readers? I see that https://godoc.org/gopkg.in/yaml.v3 has fields for anchors and aliases but guess that a reader would need to handle them explicitly.
No, I don't have any specific knowledge about parser support.
As discussed in today's call, I am planning to submit a PR that proposes using glob patterns to specify quotas and rates for groups of paths.
We discussed the YAML option but noted that it is not available in JSON and doesn't seem to be widely used in the OpenAPI community, so we chose not to take it further.
In our 1/14 meeting we discussed a desire to support richer defaults than #14 allows. This could be addressed with globbing, regular expressions, or by using a pending "overlay" capability in discussion for OpenAPI.
Following the discussion of 1/14 meeting, a potential method to have an overlay-friendly method could be to transform the rates / quotas object in an array with an explicit attribute for anchoring with different anchor mechanisms; as an example:
sla: 1.0.0
...
plans:
base:
availability: R/00:00:00Z/23:00:00Z
free:
rates:
- path: /pets/{id}
operation: get
limits:
requests:
- max: 1
period: second
- target: *.
operation: get
limits:
requests:
- max: 1
period: second
- pattern: "^mypath/*$"
operation: get
limits:
requests:
- max: 1
period: second
- id: GlobalRateLimit
limits:
requests:
- max: 1
period: secondIn the above example we have 4 different potential ways of anchoring:
- Using a path (
path: /pets/{id}). - Using a JMESPath (
target: *.) . - Using a regular expression (
pattern: "^mypath/*$"). - Using an unique id (
id: GlobalRateLimit) that will be used in combination with a separate overlay definition to link it with an actual Open API Spec document.
In case this is an accepted approach, a further discussion should be developed on whether you could use multiple anchoring methods or you should only use one of them for each limit.
Following the discussion of 05/04, we put on hold this issue until OAI TSC completes the discussion about overlays.