From 4d2670bdbfa85f2d460f5b8b0a84947ae88b61b7 Mon Sep 17 00:00:00 2001 From: Himal Date: Wed, 8 Nov 2023 10:53:02 +1100 Subject: [PATCH 1/4] Add a page on REST API rate limits --- data/nav.yml | 2 ++ pages/apis/rest_api/limits.md | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 pages/apis/rest_api/limits.md diff --git a/data/nav.yml b/data/nav.yml index 428f09e8e0..82e42478c3 100644 --- a/data/nav.yml +++ b/data/nav.yml @@ -406,6 +406,8 @@ children: - name: "Overview" path: "apis/rest-api" + - name: "Limits" + path: "apis/rest-api/limits.md" - name: "Pipelines REST API" children: - name: "Access token" diff --git a/pages/apis/rest_api/limits.md b/pages/apis/rest_api/limits.md new file mode 100644 index 0000000000..b5d11d22eb --- /dev/null +++ b/pages/apis/rest_api/limits.md @@ -0,0 +1,34 @@ + +# REST API rate limits +To ensure stability and prevent excessive or abusive calls to the server, Buildkite imposes a limit on the number of REST API requests that can be made within a minute. These limits apply to the Pipelines REST API as well as the Analytics REST API + +## Rate limits +Buildkite imposes a rate limit of 200 requests per minute for each organization. This is the cumulative limit of all API requests made by users in an organization. + +## Checking rate limit details +The rate limit status is available in the following response headers of each API call. + +- `RateLimit-Remaining` - The remaining requests that can be made within the current time window +- `RateLimit-Limit` - The current rate limit imposed on your organization. +- `RateLimit-Reset` - The number of seconds remaining until a new time window is started and limits are reset. + +For example + +```js +RateLimit-Remaining: 180 +RateLimit-Limit: 200 +RateLimit-Reset: 42 +``` + +## Exceeding the rate limit +Once the rate limit is exceeded, subsequent API requests will return a 429 HTTP status code, and the `RateLimit-Remaining` header will be 0. You should not make any further requests until the `RateLimit-Reset` specifies a new availability window. + +## Best practices to avoid rate limits +To ensure the smooth functioning and efficient use of an API, it is recommended to design your client application with some best practices in mind. Some key considerations to keep in mind when using an API include the following: + +- Implement appropriate pagination techniques when querying data. +- Use caching strategies to avoid excessive calls to the Buildkite API. +- Regulate the rate of your requests to ensure smoother distribution, by using strategies such as queues or scheduling API calls at appropriate intervals. +- Utilize metadata about your API usage, including rate limit status, to manage behaviour dynamically. +- Rate limiting is imposed across an organization. Ensure all users making requests across the organization are accounted for with rate limiting. +- It is important to be aware of `retries`, `errors`, and `loops` when designing your application, as they can easily accumulate and use up allocated quotas. From 79155cdcfb4cdc5f22101c164359f0ca47350d55 Mon Sep 17 00:00:00 2001 From: Michael Belton Date: Wed, 8 Nov 2023 13:47:53 +1100 Subject: [PATCH 2/4] Remove .md from path in navigation --- data/nav.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/nav.yml b/data/nav.yml index 82e42478c3..06eb038474 100644 --- a/data/nav.yml +++ b/data/nav.yml @@ -407,7 +407,7 @@ - name: "Overview" path: "apis/rest-api" - name: "Limits" - path: "apis/rest-api/limits.md" + path: "apis/rest-api/limits" - name: "Pipelines REST API" children: - name: "Access token" From df7132b1af038192b545bacb221fea3a06daea06 Mon Sep 17 00:00:00 2001 From: Himal Date: Wed, 8 Nov 2023 14:15:57 +1100 Subject: [PATCH 3/4] Changes to some of the wordings from GH 'commit suggestions' feature :) Co-authored-by: Michael Belton <119824349+mbelton-buildkite@users.noreply.github.com> --- pages/apis/rest_api/limits.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/pages/apis/rest_api/limits.md b/pages/apis/rest_api/limits.md index b5d11d22eb..9c30ebed7f 100644 --- a/pages/apis/rest_api/limits.md +++ b/pages/apis/rest_api/limits.md @@ -1,5 +1,6 @@ # REST API rate limits + To ensure stability and prevent excessive or abusive calls to the server, Buildkite imposes a limit on the number of REST API requests that can be made within a minute. These limits apply to the Pipelines REST API as well as the Analytics REST API ## Rate limits @@ -8,11 +9,11 @@ Buildkite imposes a rate limit of 200 requests per minute for each organization. ## Checking rate limit details The rate limit status is available in the following response headers of each API call. -- `RateLimit-Remaining` - The remaining requests that can be made within the current time window +- `RateLimit-Remaining` - The remaining requests that can be made within the current time window. - `RateLimit-Limit` - The current rate limit imposed on your organization. - `RateLimit-Reset` - The number of seconds remaining until a new time window is started and limits are reset. -For example +For example, the following headers show a situation where 180 requests can still be made in the current window, with a limit of 200 requests a minute imposed on the organization, and 42 seconds before a new time window begins. ```js RateLimit-Remaining: 180 @@ -24,11 +25,11 @@ RateLimit-Reset: 42 Once the rate limit is exceeded, subsequent API requests will return a 429 HTTP status code, and the `RateLimit-Remaining` header will be 0. You should not make any further requests until the `RateLimit-Reset` specifies a new availability window. ## Best practices to avoid rate limits -To ensure the smooth functioning and efficient use of an API, it is recommended to design your client application with some best practices in mind. Some key considerations to keep in mind when using an API include the following: +To ensure the smooth functioning and efficient use of the API, we recommend you design your client application with the following best practices in mind: - Implement appropriate pagination techniques when querying data. - Use caching strategies to avoid excessive calls to the Buildkite API. -- Regulate the rate of your requests to ensure smoother distribution, by using strategies such as queues or scheduling API calls at appropriate intervals. -- Utilize metadata about your API usage, including rate limit status, to manage behaviour dynamically. -- Rate limiting is imposed across an organization. Ensure all users making requests across the organization are accounted for with rate limiting. -- It is important to be aware of `retries`, `errors`, and `loops` when designing your application, as they can easily accumulate and use up allocated quotas. +- Regulate the rate of your requests to ensure smoother distribution by using strategies such as queues or scheduling API calls at appropriate intervals. +- Utilize metadata about your API usage, including rate limit status, to manage behavior dynamically. +- Ensure you consider all users making requests across your organization in your rate-limiting solution. +- Be aware of retries, errors, and loops when designing your application, as they can easily accumulate and use up allocated quotas. From 9d0f041c0e65688775f14433120b02474813ee71 Mon Sep 17 00:00:00 2001 From: Himal Date: Wed, 8 Nov 2023 16:37:50 +1100 Subject: [PATCH 4/4] Update pages/apis/rest_api/limits.md Co-authored-by: Michael Belton <119824349+mbelton-buildkite@users.noreply.github.com> --- pages/apis/rest_api/limits.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/apis/rest_api/limits.md b/pages/apis/rest_api/limits.md index 9c30ebed7f..e7ceafa71b 100644 --- a/pages/apis/rest_api/limits.md +++ b/pages/apis/rest_api/limits.md @@ -1,7 +1,7 @@ # REST API rate limits -To ensure stability and prevent excessive or abusive calls to the server, Buildkite imposes a limit on the number of REST API requests that can be made within a minute. These limits apply to the Pipelines REST API as well as the Analytics REST API +To ensure stability and prevent excessive or abusive calls to the server, Buildkite imposes a limit on the number of REST API requests that can be made within a minute. These limits apply to the Pipelines REST API as well as the Analytics REST API. ## Rate limits Buildkite imposes a rate limit of 200 requests per minute for each organization. This is the cumulative limit of all API requests made by users in an organization.