Design API Rate Limiting

This is the API-fairness prompt in the system design loop, and it is a gentler-looking problem than the collaborative editor or permission-scoped search. That is the trap. A rate limiter sounds like a counter with an if-statement, so the tempting move is to reach for the request-per-second cap every big-tech loop teaches. Two other guides in this catalog design exactly that limiter. The Atlassian version starts from a different unit. Before touching the mechanism, get clear on what Atlassian is actually protecting. It is a shared multi-tenant platform where thousands of companies and their installed apps all hammer the same API. The cheapest way to hurt a customer is to let one integration eat the whole budget.

The house that runs this API is worth picturing. Jira tracks issues. Confluence holds docs and wikis. Bitbucket is source control, Trello is boards. Every one of them exposes a Cloud REST API that a customer's own scripts and thousands of Marketplace add-ons call constantly. A call is not uniform work. Reading a single issue by key touches one row. Running a JQL search that returns five hundred issues with all their fields is a different animal on the database. A flat requests-per-second cap treats those two as identical. That means it either throttles the cheap calls too hard or lets the expensive ones through until the database buckles.

The Atlassian angle

Atlassian meters its Cloud API in cost points, and a call's cost scales with the work it does. Every request starts at a base cost of one point. Expensive operations add more points for the objects they return and the work they trigger. So a bulk JQL search that hydrates hundreds of issues draws down far more of a tenant's budget than a single-issue read. The burst limit is a token bucket applied per tenant per endpoint, and the enforcement point is the tenant, so all of a customer's integrations draw from the same bucket for a given endpoint. On top of that sits an hourly quota allocated per tenant per app. Lead with the cost model and the per-tenant bucket.