ometere123/the-skills-bible/api-rate-quota-engineer

API Rate and Quota Engineer

Purpose

Build and operate predictable and equitable API consumption within provider and downstream capacity.

Use this skill when

• Design API request limits, concurrency limits, quotas, weighted cost, burst handling, fairness, headers, and consumer policy.
• Independent producers and consumers need an explicit, supported contract.
• Interface behaviour must remain reliable across versions, failures, and organisational boundaries.
• Developer experience and operational evidence are part of the delivery outcome.

Do not use this skill as the primary workflow when

• The work is entirely internal to one module with no independent consumer contract.
• A previously defined generic architecture or security workflow is the dominant task.
• The requested change cannot be authorised, observed, or supported through its lifecycle.

Required inputs

• Consumer workflows, constraints, and expected outcomes.
• Current specifications, schemas, examples, SDKs, and implementation behaviour.
• Identity, tenant, data, permission, and secret requirements.
• Workload, payload, latency, quota, and dependency limits.
• Supported versions, release policy, incidents, and consumer inventory.

Classify missing information as blocking, important, or optional. Inspect the actual specifications, code, gateway policies, SDKs, credentials, usage, delivery evidence, and support history before asking for information that can be verified directly.

Core operating principles

• Design interfaces around stable consumer outcomes rather than internal implementation structure.
• Treat schemas, examples, documentation, SDKs, policies, and compatibility rules as versioned production artefacts.
• Prefer explicit contracts, deterministic validation, idempotent effects, and bounded failure semantics.
• Keep identity, tenant, permission, quota, and ownership decisions authoritative and server-enforced.
• Preserve backward compatibility deliberately and make breaking changes visible, testable, and migratable.
• Design retries, timeouts, cancellation, pagination, ordering, and partial failure as part of the public contract.
• Protect consumers from implementation churn while avoiding abstractions that hide important differences.
• Make integrations observable end to end through stable identifiers, correlation, delivery state, and reconciliation.
• Provide realistic examples, sandboxes, diagnostics, and migration guidance so consumers can succeed independently.
• Govern the full lifecycle from discovery and onboarding through change, deprecation, offboarding, and retirement.

Workflow

1. Define the consumer outcome

• State the required outcome for predictable and equitable API consumption within provider and downstream capacity.
• Identify unacceptable ambiguity, side effects, and consumer failure.

2. Map actors and trust boundaries

• Map applications, users, tenants, partners, plans, internal services, and dependency owners.
• Assign provider, consumer, platform, security, support, and decision ownership.

3. Define the public contract

• Specify limiting identities, operation weights, burst rules, sustained rates, quotas, concurrency, and reset semantics.
• Separate public semantics from internal implementation and document authoritative behaviour.

4. Secure identity and data

• Design trusted identity, bypass prevention, limit-state protection, exception governance, and abuse detection.
• Validate every trust decision at the authoritative boundary and minimise exposed data.

5. Engineer reliability

• Define retry guidance, limit-store failure, reservation, graceful degradation, and quota reconciliation.
• Make partial success, unknown outcomes, cancellation, and recovery visible to consumers.

6. Bound scalability and cost

• Control global and regional capacity, expensive operations, downstream quotas, distributed counters, and fairness.
• Set explicit limits, fair-use rules, capacity assumptions, and dependency protections.

7. Design developer experience

• Provide clear limit documentation, remaining or reset information, test environments, SDK handling, and upgrade guidance.
• Ensure a new consumer can complete the critical workflow without undocumented support knowledge.

8. Validate compatibility

• Test plan changes, old headers, client backoff, approximate enforcement, and policy-version compatibility.
• Use supported consumers, generated clients, contract fixtures, and mixed-version scenarios.

9. Instrument operations

• Observe accepted and rejected demand, wait time, cost units, quota use, false rejection, bypass attempts, and exceptions.
• Correlate consumer-visible failures with provider, dependency, contract, and release evidence.

10. Govern the lifecycle

• Define publication, ownership, support, change review, deprecation, offboarding, and retirement.
• Record residual risks, exceptions, migration deadlines, and review triggers.

Decision rules

Required outputs

• Consumer outcome and scope.
• Actor, ownership, and trust map.
• Versioned interface or integration contract.
• Identity, permission, and data controls.
• Reliability and recovery semantics.
• Limits, capacity, and fairness policy.
• Developer onboarding and diagnostic assets.
• Compatibility and migration evidence.
• Operational telemetry and support model.
• Lifecycle, exception, and retirement record.

API, SDK, and integration quality gates

• Consumer gate: Target consumers, workflows, constraints, and success outcomes are explicit.
• Contract gate: Inputs, outputs, errors, state changes, ordering, retries, and limits are precise.
• Identity gate: Authentication, authorisation, tenant, delegation, and credential lifecycle are enforced.
• Compatibility gate: Supported versions, additive changes, breaking changes, and migration paths are documented and tested.
• Reliability gate: Timeouts, idempotency, retries, partial failure, reconciliation, and degraded behaviour are operational.
• Security gate: Untrusted inputs, callbacks, secrets, permissions, and third-party data are bounded.
• Developer gate: Documentation, examples, diagnostics, sandbox behaviour, and SDK ergonomics support independent adoption.
• Observability gate: Requests, deliveries, retries, transformations, failures, and partner outcomes are traceable.
• Scalability gate: Quotas, pagination, payload limits, batching, concurrency, and dependency ceilings are explicit.
• Lifecycle gate: Onboarding, change, deprecation, offboarding, data deletion, and retirement have accountable owners.

Evidence standard

For consequential conclusions, identify the exact API or protocol version, schema, SDK version, environment, consumer, identity, tenant, payload, dependency state, request or delivery identifier, and time window. Distinguish observed contract behaviour, supported inference, and undocumented assumptions. Do not claim compatibility from schema comparison alone when semantics or side effects differ.

Failure handling and escalation

Pause or escalate when:

• The authoritative contract, owner, or consumer expectation is unclear.
• Credentials, tenant boundaries, permissions, callback destinations, or data rights cannot be verified.
• Retrying may duplicate money movement, messages, records, or other external side effects.
• A breaking change affects unknown or uncontactable consumers.
• Third-party behaviour conflicts with documented guarantees or creates active data loss.
• Production testing could send real communications, incur charges, or affect external users.
• Residual integration, security, privacy, or operational risk exceeds delegated authority.

Report the exact blocker, verified state, affected consumers, evidence, safe options, and smallest required decision.

Common anti-patterns

• Limiting only by IP.
• Counting every operation equally.
• Synchronized quota resets.
• Retry guidance that creates storms.
• Multiple keys bypassing tenant quotas.
• Permanent exceptions.

Completion checklist

• [ ] Consumer outcomes and exclusions are explicit.
• [ ] Provider and consumer ownership is recorded.
• [ ] The contract includes failure and side-effect semantics.
• [ ] Identity, tenant, and data boundaries are enforced.
• [ ] Retries, timeouts, and unknown outcomes are safe.
• [ ] Limits and dependency ceilings are explicit.
• [ ] Independent consumers can integrate from published assets.
• [ ] Supported versions pass compatibility tests.
• [ ] Operations can correlate and reconcile failures.
• [ ] Deprecation and retirement are executable.

Interface and integration record

# Interface and Integration Record
 
## Outcome
[Consumer workflow, partner exchange, SDK use case, or integration result]
 
## Scope
[Providers, consumers, environments, identities, tenants, data, and exclusions]
 
## Contract
[Operations, schemas, errors, ordering, pagination, quotas, and side effects]
 
## Compatibility
[Versions, supported clients, additive rules, breaking changes, and migration]
 
## Reliability
[Timeouts, retries, idempotency, delivery, reconciliation, and recovery]
 
## Security and privacy
[Credentials, permissions, validation, secrets, callbacks, and data lifecycle]
 
## Developer experience
[Documentation, examples, SDKs, sandbox, diagnostics, and support]
 
## Observability
[Identifiers, traces, logs, metrics, dashboards, and partner evidence]
 
## Residual risk
[Known limitations, owner, acceptance, expiry, and communication]
 
## Lifecycle
[Rollout, deprecation, offboarding, deletion, and retirement]

Related skills

• rate-limiting-fairness-engineer
• api-gateway-management-engineer
• sdk-resilience-engineer
• developer-portal-engineer

Maintenance rules

Review this skill when consumers, schemas, protocols, providers, SDKs, limits, regulations, or operational dependencies change; incidents reveal missing contract behaviour; the workflow becomes tied to one vendor; the file approaches 500 lines; or reusable schemas, examples, validators, fixtures, or compatibility tests would improve execution.