API Design Pattern of the Week 15: Rate Limit

A pattern from the book “Patterns of API Design: Simplifying Integration with Loosely Coupled Message Exchanges”

Published in

ZIO’s Blog

4 min readOct 26, 2023

The first 14 patterns in the “API Design Pattern of the Week” series came as LinkedIn articles. All patterns in the series are listed in this overview story.

Note: This online excerpt of the pattern predates the final version in the book.

Context

An API endpoint and the API contract defining operations, messages, and data representations have been established. An API Description has been defined that specifies messages exchange patterns and protocol. Clients of the API might have signed up with the provider and have agreed to the terms and conditions that govern the usage of the endpoint.

Problem

How can the API provider prevent API clients from excessive API usage?

What exactly is deemed excessive needs to be defined by the API provider. A flat rate subscription typically imposes different limitations than a free billing plan. See the Pricing Plan pattern for a detailed discussion of the trade-offs of different subscription models.

Forces

When preventing excessive API usage that may harm provider operations or other clients, solutions to the following design issues have to be found:

Economic aspects
Performance
Reliability
Impact and severity of risks of API abuse
Client awareness

These pattern forces are explained in depth in the book.

Solution Sketch

Introduce and enforce a Rate Limit to safeguard against API clients that overuse the API.

Example

GitHub uses this pattern to control access to its RESTful HTTP API: Once a Rate Limit is exceeded, subsequent requests are answered with HTTP status code 429 Too Many Requests. To inform clients about the current state of each Rate Limits and to help clients manage their allowance of tokens, custom HTTP headers are sent with each rate-limited response.

The following code listing shows an excerpt of such a rate-limited response from the GitHub API. The API has a limit of 60 requests per hour, of which 59 remain:

GET https://api.github.com/users/misto 

HTTP/1.1 200 OK ... 
X-RateLimit-Limit: 60 
X-RateLimit-Remaining: 59 
X-RateLimit-Reset: 1498811560

The X-RateLimit-Reset indicates the time when the limit will be reset with a Unix timestamp (Unix timestamps count the number of seconds since January 1st, 1970).

Consequences

Forces resolution and other consequences are discussed in our book.

Known Uses

See pattern coverage on our website api-patterns.org.

Related Patterns

The details of a Rate Limit can be part of a Service Level Agreement. A Rate Limit can be dependent on the client’s subscription level, which is further described in the Pricing Plan pattern. In such cases the Rate Limit is used to enforce different billing levels of the Pricing Plan.

To observe individual clients and manage their allowances, the service provider needs to identify the client making a request. Therefore, clients need to present some form of identification (e.g. an API Key, an IP address or another authentication practice) so that the API provider can do the bookkeeping.

A Wish List and a Wish Template can help to ensure that data-bound Rate Limits are not violated. The current state of the Rate Limit, e.g., how many requests remain in the current billing period, can be communicated via a Context Representation.

The systems management patterns (Hohpe and Woolf 2003) can help to implement metering and can thus also be used as enforcement points. For example, a Control Bus can be used to increase or decrease certain limits dynamically at runtime. Leaky Bucket Counter (Hanmer 2007) offers a possible implementation variant for Rate Limit.

References

Hanmer, Robert. 2007. Patterns for Fault Tolerant Software. Wiley.

Hohpe, Gregor, and Bobby Woolf. 2003. Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions. Addison-Wesley.

Zimmermann, Olaf and Stocker, Mirko and Lübke, Daniel and Zdun, Uwe and Pautasso, Cesare. 2022. Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges, Vaughn Vernon Signature Series, Addison-Wesley Professional.

The book features the full pattern texts plus API domain model, decision models, pattern adoption stories.

This pattern originally appeared on the https://api-patterns.org website.

The pattern presentation follows the standard format for patterns, from context to forces, problem, solution, consequences and known uses. Find out why.