APIMGMT-1962: Enhance rate limiting documentation with route-specific backoff details and configuration options. Include YAML example for enabling backoff in API routes across multiple versions#1105
Conversation
… backoff details and configuration options. Include YAML example for enabling backoff in API routes across multiple versions.
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| ### Route-owner configuration | ||
|
|
||
| Route owners can enable backoff in the API route specification for routes that need escalating retry delays. The authoritative route YAML is maintained in `cloud-api-client-common/api-route-specs/sp-gateway-routes.yaml`. | ||
|
|
||
| ```yaml | ||
| backOffConfig: | ||
| enabled: true | ||
| intervalThreshold: 3 # Distinct violated intervals before backoff triggers | ||
| tiers: [60, 300, 600, 1200] # Backoff durations per escalation tier, in seconds | ||
| violationWindow: 120 # Window for counting violated intervals, in seconds | ||
| tierMemoryWindow: 3600 # How long to remember the last tier after expiry, in seconds | ||
| redisTimeoutMs: 5 # Max time allowed per Redis backoff operation, in milliseconds | ||
| ``` | ||
|
|
||
| Backoff is active only when the route has `backOffConfig.enabled: true` and the gateway backoff rollout control is enabled. Omitted or non-positive values fall back to the gateway defaults. |
There was a problem hiding this comment.
🔴 The new "Route-owner configuration" subsection (added to all 6 rate-limit.md files) is internal SailPoint engineering content that doesn't belong on the public developer portal. It's explicitly addressed to "Route owners," references an internal repo path (cloud-api-client-common/api-route-specs/sp-gateway-routes.yaml) that external readers can't access, and exposes internal gateway knobs (redisTimeoutMs, the "gateway backoff rollout control" feature flag) that public API consumers cannot configure. The preceding "Route-specific backoff" section already covers everything external consumers need — please remove this subsection from all 6 files and keep it in internal docs instead.
Extended reasoning...
What the bug is
The PR adds two new subsections to docs/api/rate-limit.md and its 5 versioned siblings (beta, v3, v2024, v2025, v2026). The first — Route-specific backoff — is appropriately scoped for external API consumers: it tells them Retry-After may be longer than the default reset window and instructs them to honor it and reduce concurrency. That part is fine.
The second — Route-owner configuration — is internal-only material that has been published to the public developer portal. The repository's own README states that developer.sailpoint.com is the public-facing developer portal, so the audience for these pages is external API consumers, not SailPoint engineers.
How the audience mismatch manifests
Four concrete tells in the added block show it's aimed at the wrong audience:
- Explicit addressee. The opening sentence says "Route owners can enable backoff in the API route specification…" — i.e., the SailPoint engineers who own gateway route specs, not the external developers reading this site.
- Internal repo path. "The authoritative route YAML is maintained in
cloud-api-client-common/api-route-specs/sp-gateway-routes.yaml." This is a private SailPoint engineering repo path. External readers cannot browse, clone, or modify that file. - Internal implementation knobs.
redisTimeoutMsties documentation to the gateway's internal Redis-backed implementation. External consumers neither see nor control Redis behavior. - Internal feature flag. "…and the gateway backoff rollout control is enabled" references an internal rollout/feature flag that external readers cannot inspect or toggle.
Why the preceding section is already sufficient
For the external audience, only the answer to "what do I do when this happens?" matters. That is fully covered by the prior subsection: clients still receive 429 Too Many Requests, must honor the Retry-After value, and should reduce concurrency / spread requests. Adding the YAML config block teaches external readers nothing actionable — they can't apply it.
Impact
- Leaks internal architecture details (Redis, internal feature flag, internal route-spec YAML path) onto a public site.
- Confuses external readers, who may attempt to apply a "configuration" they have no way to set.
- Amplified 6× because the same block was duplicated across every version-specific
rate-limit.md.
Step-by-step proof
- Open
docs/api/rate-limit.mdon the rendered site (developer.sailpoint.com). The README states this repo "contains the complete build, with assets, for everything seen on developer.sailpoint.com", so the page is public. - Scroll past "Route-specific backoff" — appropriate, audience-neutral content.
- Reach the new "Route-owner configuration" subsection. As an external developer, ask: "How do I edit
cloud-api-client-common/api-route-specs/sp-gateway-routes.yaml?" Answer: you cannot — it lives in a SailPoint-internal repo. - Ask: "How do I enable the gateway backoff rollout control?" Answer: you cannot — it is an internal SailPoint feature flag.
- Ask: "What do I do with
redisTimeoutMs: 5?" Answer: nothing — you do not run SailPoint's gateway or its Redis. - Repeat for the 5 other versioned copies (
beta,v3,v2024,v2025,v2026) — the same internal-only block is duplicated everywhere.
How to fix
Remove the entire "Route-owner configuration" subsection (including its YAML code block and the trailing "Backoff is active only when…" paragraph) from all 6 files. Keep "Route-specific backoff", which is correctly scoped for the public audience. If the route-owner content is still needed by SailPoint engineers, host it in an internal docs location (internal Confluence, the cloud-api-client-common repo's README, etc.) rather than on the public developer portal.
|
|
||
| Always wait for the full `Retry-After` value before sending another request. If your integration continues to exceed limits, reduce request concurrency or spread requests over a longer period so each `client_id` stays within the documented limits. | ||
|
|
||
| ### Route-owner configuration |
There was a problem hiding this comment.
Like Claude mentioned, you should remove the Route-owner configuration section. Non-SailPoint devs don't need to know about the internals of sp-gateway.
|
|
||
| - **Retry-After**: [seconds to wait before rate limit resets] | ||
|
|
||
| ### Route-specific backoff |
There was a problem hiding this comment.
This is good, but maybe expand this section with an explanation of what a backoff is, and when it is applied. Customers are very concerned about rate limiting; I'm still getting questions about the addition of client_id to the rate limit key.
2 participants
…