From a998b81be78cc45a1c7a1510fef2967b970f9081 Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Thu, 11 Apr 2024 19:48:44 +0000 Subject: [PATCH 1/4] backport of commit 291092efa2484b1930cac0a78052eeb1ee85db52 --- website/content/docs/api-clients/api/index.mdx | 8 ++++++++ .../content/docs/api-clients/api/rate-limiting.mdx | 11 +++++------ 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/website/content/docs/api-clients/api/index.mdx b/website/content/docs/api-clients/api/index.mdx index c3ea4e2ad4..db307b5ea5 100644 --- a/website/content/docs/api-clients/api/index.mdx +++ b/website/content/docs/api-clients/api/index.mdx @@ -82,6 +82,14 @@ The following method conventions are used within Boundary's API: `DELETE` is used for deleting a specific resource, and is only used against a particular resource path. +## HTTP headers + +Clients that make requests to the controller API can inspect HTTP response headers to understand the configured limits and current usage. +Responses may contain the following headers: + +- `RateLimit` - Provides the current limit, number of remaining requests, and the time at which the quota will reset for the limit that is closest to being exhausted for the requested resource and action. +- `RateLimit-Policy` - Describes the limits for the requested resource and action. + ## Manage system resources If your controllers try to process every API request, they may either run out of resources or overwhelm the database server. diff --git a/website/content/docs/api-clients/api/rate-limiting.mdx b/website/content/docs/api-clients/api/rate-limiting.mdx index fc2f25911e..16d5feedaf 100644 --- a/website/content/docs/api-clients/api/rate-limiting.mdx +++ b/website/content/docs/api-clients/api/rate-limiting.mdx @@ -41,17 +41,16 @@ The default limits for all other actions are: You can override the default settings and configure other specific limitations using the `api_rate_limit` stanza in the controller configuration. -## HTTP headers +## Rate limiting HTTP headers Clients that make requests to the controller API can inspect HTTP response headers to understand the configured limits and current usage. -Each response contains the following headers: +Each response contains the `RateLimit` and `RateLimit-Policy` headers. -- `RateLimit` - Provides the current limit, number of remaining requests, and the time at which the quota will reset for the limit that is closest to being exhausted for the requested resource and action. -- `RateLimit-Policy` - Describes the limits for the requested resource and action. - -If the request is limited, Boundary sends the client a 429 HTTP status code with a `Retry-After` header. +If the request is rate limited, Boundary sends the client a 429 HTTP status code with a `Retry-After` header. The `Retry-After` header contains the number of seconds the client should wait before it sends the request again. +For more information, refer to [HTTP headers](/boundary/docs/api-clients/api#http-headers). + ## More information Refer to the [controller stanza](/boundary/docs/configuration/controller#api_rate_limit) documentation for the specific `api_rate_limit` configuration options. From bc117eee830e0553edb304ed654aafdb2e08573a Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Mon, 29 Apr 2024 20:12:04 +0000 Subject: [PATCH 2/4] backport of commit 7612471bf5be5759efd97530b5347a09bea3da2e --- website/content/docs/api-clients/api/index.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/website/content/docs/api-clients/api/index.mdx b/website/content/docs/api-clients/api/index.mdx index db307b5ea5..6fb380d20e 100644 --- a/website/content/docs/api-clients/api/index.mdx +++ b/website/content/docs/api-clients/api/index.mdx @@ -89,6 +89,7 @@ Responses may contain the following headers: - `RateLimit` - Provides the current limit, number of remaining requests, and the time at which the quota will reset for the limit that is closest to being exhausted for the requested resource and action. - `RateLimit-Policy` - Describes the limits for the requested resource and action. +- `x-correlation-id` - Indicates that an API request that came in to Boundary is also related to an audit event in Vault. ## Manage system resources From d0b55d0eb889f3157db94eeaccfced45a5a6a6fb Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Mon, 29 Apr 2024 22:06:01 +0000 Subject: [PATCH 3/4] backport of commit f4ec5d014a6d93e3a9b222fc7fccb3041e8e5709 --- website/content/docs/api-clients/api/index.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/website/content/docs/api-clients/api/index.mdx b/website/content/docs/api-clients/api/index.mdx index 6fb380d20e..f4235a3104 100644 --- a/website/content/docs/api-clients/api/index.mdx +++ b/website/content/docs/api-clients/api/index.mdx @@ -89,7 +89,10 @@ Responses may contain the following headers: - `RateLimit` - Provides the current limit, number of remaining requests, and the time at which the quota will reset for the limit that is closest to being exhausted for the requested resource and action. - `RateLimit-Policy` - Describes the limits for the requested resource and action. -- `x-correlation-id` - Indicates that an API request that came in to Boundary is also related to an audit event in Vault. +- `X-Correlation-ID` - Identifies a transaction over a series of requests and responses. +The `X-Correlation-ID` header is a universally unique identifier (UUIDv4). +If you provide an `X-Correlation-ID` header in an HTTP request, Boundary logs that value for all audit events related to the request. +It uses that value as the header when it makes related requests to an external system, such as Vault, so that you can correlate the event between the product logs. ## Manage system resources From 7821660f8a10e79873fda361453df617277e1aba Mon Sep 17 00:00:00 2001 From: Dan Heath <76443935+Dan-Heath@users.noreply.github.com> Date: Mon, 29 Apr 2024 22:16:36 +0000 Subject: [PATCH 4/4] backport of commit 257ff07b830dade9f02fe34f3ab1cf321b1f2062 --- website/content/docs/api-clients/api/index.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/content/docs/api-clients/api/index.mdx b/website/content/docs/api-clients/api/index.mdx index f4235a3104..7281f4f12d 100644 --- a/website/content/docs/api-clients/api/index.mdx +++ b/website/content/docs/api-clients/api/index.mdx @@ -92,7 +92,8 @@ Responses may contain the following headers: - `X-Correlation-ID` - Identifies a transaction over a series of requests and responses. The `X-Correlation-ID` header is a universally unique identifier (UUIDv4). If you provide an `X-Correlation-ID` header in an HTTP request, Boundary logs that value for all audit events related to the request. -It uses that value as the header when it makes related requests to an external system, such as Vault, so that you can correlate the event between the product logs. +It then uses that value as the header when it makes related requests to an external system, such as Vault, so that you can correlate the event between the product logs. +If you do not provide an `X-Correlation-ID` header, Boundary generates a unique value for each incoming request. ## Manage system resources