diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-circuit-breaker-config.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-circuit-breaker-config.png
new file mode 100644
index 0000000000..c4bee2ebb1
Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-circuit-breaker-config.png differ
diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-circuit-breaker.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-circuit-breaker.png
new file mode 100644
index 0000000000..7b8abd6827
Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-circuit-breaker.png differ
diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-enforce-timeout-config.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-enforce-timeout-config.png
new file mode 100644
index 0000000000..81afecb3fc
Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-enforce-timeout-config.png differ
diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-enforce-timeout.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-enforce-timeout.png
new file mode 100644
index 0000000000..3e351e9b5f
Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-enforce-timeout.png differ
diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-method-transform-config.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-method-transform-config.png
new file mode 100644
index 0000000000..8fd8927ad3
Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-method-transform-config.png differ
diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-method-transform.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-method-transform.png
new file mode 100644
index 0000000000..d2e138a1ee
Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-method-transform.png differ
diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-header-added.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-header-added.png
new file mode 100644
index 0000000000..fdea92a5b4
Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-header-added.png differ
diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-header-api-level.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-header-api-level.png
new file mode 100644
index 0000000000..c3d327d884
Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-header-api-level.png differ
diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-header-api-new-header.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-header-api-new-header.png
new file mode 100644
index 0000000000..02e46c42ce
Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-header-api-new-header.png differ
diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-header-new.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-header-new.png
new file mode 100644
index 0000000000..8c8699aaf7
Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-header-new.png differ
diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-header.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-header.png
new file mode 100644
index 0000000000..84ee26ff3b
Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-header.png differ
diff --git a/tyk-docs/content/advanced-configuration/transform-traffic/request-method-transform.md b/tyk-docs/content/advanced-configuration/transform-traffic/request-method-transform.md
index 1d27643fff..00e304e703 100755
--- a/tyk-docs/content/advanced-configuration/transform-traffic/request-method-transform.md
+++ b/tyk-docs/content/advanced-configuration/transform-traffic/request-method-transform.md
@@ -1,36 +1,36 @@
---
date: 2017-03-23T17:45:01Z
-title: Request Method Transform
-menu:
- main:
- parent: "Transform Traffic"
-weight: 6
+title: Request Method Transformation
+tags: ["Request Transform", "Method Transform", "transform"]
+description: "How to transform the HTTP Method for an API Request"
---
-It is now possible, as of Tyk Gateway v2.2, to change the method of a request. To enable, add to your extended paths:
+Tyk's Request Method Transform middleware allows you to modify the HTTP method of incoming requests to an API endpoint prior to the request being proxied to the upstream service. You might use this to map `POST` requests from clients to upstream services that support only `PUT` and `DELETE` operations, providing a modern interface to your users. It is a simple middleware that changes only the method and not the payload or headers. You can, however, combine this with the [Request Header Transform]({{< ref "transform-traffic/request-headers" >}}) and [Request Body Tranform]({{< ref "transform-traffic/request-body" >}}) to apply more complex transformation to requests.
-```{.copyWrapper}
-method_transforms: [
- {
- path: "post",
- method: "GET",
- to_method: "POST"
- }
-],
-```
-{{< note success >}}
-**Note**
+## When to use request method transformation
+#### Simplifying API consumption
+In cases where an upstream API requires different methods (e.g. `PUT` or `DELETE`) for different functionality but you want to wrap this in a single client-facing API, you can provide a simple interface offering a single method (e.g. `POST`) and then use the method transform middleware to map requests to correct upstream method.
-This feature is very simple at the moment, and only changes the type of method, it does not handle the message data of the request body. However, a combination of method transform, context variables and body transformations can be used to achieve a similar effect.
-{{< /note >}}
+#### Enforcing API governance and standardisation
+You can use the transform middleware to ensure that all requests to a service are made using the same HTTP method, regardless of the original method used by the client. This can help maintain consistency across different client applications accessing the same upstream API.
+#### Error Handling and Redirection
+You can use the method transformation middleware to handle errors and redirect requests to different endpoints, such as changing a DELETE request to a GET request when a specific resource is no longer available, allowing for graceful error handling and redirection.
-### Using the Dashboard
+#### Testing and debugging
+Request method transformation can be useful when testing or debugging API endpoints; temporarily changing the request method can help to identify issues or test specific functionalities.
-To do this from the Dashboard, from the **API Endpoint Designer** select **method transform** from the plugins drop-down list on the endpoint you want to transform from.
+## How the request method transform works
+This is a very simple middleware that is assigned to an endpoint and configured with the HTTP method to which the request should be modified. The Request Method Transform middleware modifies the request method for the entire request flow, not just for the specific upstream request, so all subsequent middleware in the processing chain will use the new (transformed) method.
-{{< img src="/img/2.10/method_transform.png" alt="Method Transform" >}}
+
-Then select the path you wish to change to.
+If you're using Tyk OAS APIs, then you can find details and examples of how to configure the request method transform middleware [here]({{< ref "product-stack/tyk-gateway/middleware/request-method-tyk-oas" >}}).
-{{< img src="/img/2.10/method_transform2.png" alt="Method Path" >}}
+If you're using Tyk Classic APIs, then you can find details and examples of how to configure the request method transform middleware [here]({{< ref "product-stack/tyk-gateway/middleware/request-method-tyk-classic" >}}).
+
+
\ No newline at end of file
diff --git a/tyk-docs/content/context-variables.md b/tyk-docs/content/context-variables.md
index ad7e1c275a..daf40f58a0 100755
--- a/tyk-docs/content/context-variables.md
+++ b/tyk-docs/content/context-variables.md
@@ -10,19 +10,16 @@ aliases:
- /getting-started/key-concepts/context-variables/
---
-Context variables are extracted from the request at the start of the middleware chain, and must be explicitly enabled in order for them to be made available to your transforms. These values can be very useful for later transformation of request data, for example, in converting a Form-based POST into a JSON-based PUT or to capture an IP address as a header.
+Context variables are extracted from the request at the start of the middleware chain. These values can be very useful for later transformation of request data, for example, in converting a form POST request into a JSON PUT request or to capture an IP address as a header.
-### Enable Context Variables
-1. In the your Tyk Dashboard, select `APIs` from the `System Management` menu
-2. Open the API you want to add Context Variable to.
-3. Select the `Advanced Options` tab and select `Enable context variables`
-
-{{< img src="/img/2.10/context_variables.png" alt="Context Variables" >}}
+{{< note success >}}
+**Note**
-If not using a Tyk Dashboard, add the field `enable_context_vars` to your API definition file at root level and set it to `true`.
+When using Tyk Classic APIs, you must [enable]({{< ref "#enabling-context-variables-for-use-with-tyk-classic-apis" >}}) context variables for the API to be able to access them. When using Tyk OAS APIs, the context variables are always available to the context-aware middleware.
+{{< /note >}}
-### The available context variables are:
+## Available context variables
* `request_data`: If the inbound request contained any query data or form data, it will be available in this object. For the header injector Tyk will format this data as `key:value1,value2,valueN;key:value1,value2` etc.
* `path_parts`: The components of the path, split on `/`. These values should be in the format of a comma delimited list.
* `token`: The inbound raw token (if bearer tokens are being used) of this user.
@@ -35,14 +32,14 @@ If not using a Tyk Dashboard, add the field `enable_context_vars` to your API de
For example, to get the value stored in `test-header`, the syntax would be `$tyk_context.headers_Test_Header`.
-### Plugins that can use context variables:
+## Middleware that can use context variables:
Context variables are exposed in three middleware plugins but are accessed differently depending on the caller as follows:
1. URL Rewriter - Syntax is `$tyk_context.CONTEXTVARIABLES`. See [URL Rewriting]({{< ref "transform-traffic/url-rewriting" >}}) for more details.
2. Modify Headers - Syntax is `$tyk_context.CONTEXTVARIABLES`. See [Request Headers]({{< ref "transform-traffic/request-headers" >}}) for more details.
3. Body Transforms - Syntax is `{{ ._tyk_context.CONTEXTVARIABLES }}`. See [Body Transforms]({{< ref "transform-traffic/request-body#a-name-request-body-context-data-a-context-data" >}}) for more details.
-### Example use of context variables
+## Example use of context variables
#### Examples of the syntax to use with all the available context varibles:
```
@@ -75,4 +72,13 @@ Context variables are exposed in three middleware plugins but are accessed diffe
"X-Req-Id": "e3e99350-b87a-4d7d-a75f-58c1f89b2bf3",
"X-Request-Data": "key1:val1;key2:val2",
"X-Token": "5bb2c2abfb6add0001d65f699dd51f52658ce2d3944d3d6cb69f07a2"
-```
\ No newline at end of file
+```
+
+## Enabling Context Variables for use with Tyk Classic APIs
+1. In the your Tyk Dashboard, select `APIs` from the `System Management` menu
+2. Open the API you want to add Context Variable to
+3. Click the `Advanced Options` tab and then select the `Enable context variables` option
+
+{{< img src="/img/2.10/context_variables.png" alt="Context Variables" >}}
+
+If not using a Tyk Dashboard, add the field `enable_context_vars` to your API definition file at root level and set it to `true`.
\ No newline at end of file
diff --git a/tyk-docs/content/getting-started/using-oas-definitions/oas-reference.md b/tyk-docs/content/getting-started/using-oas-definitions/oas-reference.md
index 57edaf38dd..2006d9cd46 100644
--- a/tyk-docs/content/getting-started/using-oas-definitions/oas-reference.md
+++ b/tyk-docs/content/getting-started/using-oas-definitions/oas-reference.md
@@ -24,9 +24,9 @@ If there's a feature you're looking to use that isn't yet implemented, let us kn
|---------------------------------------|------------------|---------------|
| API Name | ✅ | ✅ |
| Status (draft/active) | ✅ | ✅ |
-| API Categories | ❌️ | ❌️ |
+| API Categories | ✅ | ✅ |
| API ID/API URL(s) | ✅ | ✅ |
-| API Ownership | ❌️ | ❌️ |
+| API Ownership | ✅ | ✅ |
| API Versioning | ✅ | ✅ |
### Traffic Routing
@@ -70,7 +70,7 @@ If there's a feature you're looking to use that isn't yet implemented, let us kn
| Analytics API Tagging (tag_headers) | ❌️ | ❌️ |
| expire_analytics_after | ❌️ | ❌️ |
| Do not track Analytics (per API) | ❌️ | ❌️ |
-| Detailed recording (in Log Browser) | ❌️ | ❌️ |
+| Detailed recording (in Log Browser) | ✅ | ✅ |
| Config Data | ✅ | ✅ |
| Context Variables | ❌️ | ❌️ |
| CORS | ✅ | ✅ |
@@ -82,8 +82,8 @@ If there's a feature you're looking to use that isn't yet implemented, let us kn
| Batch Requests | ❌️ | ❌️ |
| Segment Tags | ✅ | ✅ |
| Internal API (not exposed by Gateway) | ✅ | ✅ |
-| Global Header Transform | ❌️ | ❌️ |
-| API-level Rate Limit | ❌️ | ❌️ |
+| Global Header Transform | ✅ | ✅ |
+| API-level Rate Limit | ✅ | ✅ |
| Webhooks | ❌️ | ❌️ |
| Preserve Host Header | ❌️ | ❌️ |
| Transport (proxy.transport) | ❌️ | ❌️ |
@@ -94,20 +94,20 @@ If there's a feature you're looking to use that isn't yet implemented, let us kn
|---------------------------------------|------------------|---------------|
| Allow | ✅ | ✅ |
| Block | ✅ | ✅ |
-| Cache | ✅ | ❌️ |
-| Circuit Breaker | ❌️ | ❌️ |
-| Track Endpoint | ❌️ | ❌️ |
-| Do Not Track | ❌️ | ❌️ |
-| Enforced Timeout | ✅ | ❌️ |
+| Cache | ✅ | ✅ |
+| Circuit Breaker | ✅ | ✅ |
+| Track Endpoint | ✅ | ✅ |
+| Do Not Track | ✅ | ✅ |
+| Enforced Timeout | ✅ | ✅ |
| Ignore Authentication | ✅ | ✅ |
-| Internal Endpoint | ❌️ | ❌️ |
-| URL Rewrite | ❌️ | ❌️ |
+| Internal Endpoint | ✅ | ✅ |
+| URL Rewrite | ✅ | ✅ |
| Validate Request | ✅ | ✅ |
-| Request Size Limit | ❌️ | ❌️ |
-| Request Method Transform | ✅ | ❌️ |
-| Request Header Transform | ❌️ | ❌️ |
+| Request Size Limit | ✅ | ✅ |
+| Request Method Transform | ✅ | ✅ |
+| Request Header Transform | ✅ | ✅ |
| Request Body Transform | ✅ | ✅ |
-| Response Header Transform | ❌️ | ❌️ |
+| Response Header Transform | ✅ | ✅ |
| Response Body Transform | ✅ | ✅ |
| Mock Response | ✅ | ✅ |
| Virtual Endpoint | ✅ | ✅ |
diff --git a/tyk-docs/content/planning-for-production/ensure-high-availability/circuit-breakers.md b/tyk-docs/content/planning-for-production/ensure-high-availability/circuit-breakers.md
index 3db999e469..89e2beb6be 100755
--- a/tyk-docs/content/planning-for-production/ensure-high-availability/circuit-breakers.md
+++ b/tyk-docs/content/planning-for-production/ensure-high-availability/circuit-breakers.md
@@ -3,133 +3,107 @@ date: 2017-03-24T11:02:59Z
title: Circuit Breakers
tags: ["High Availability", "SLAs", "Uptime", "Monitoring", "Circuit Breaker"]
description: "How to configure the Tyk Circuit Breaker to manage failing requests"
-menu:
- main:
- parent: "Ensure High Availability"
-weight: 3
aliases:
- /ensure-high-availability/circuit-breakers/
---
-## Overview
+A circuit breaker is a protective mechanism that helps to maintain system stability by preventing repeated failures and overloading of services that are erroring. When a network or service failure occurs, the circuit breaker prevents further calls to that service, allowing the affected service time to recover while ensuring that the overall system remains functional. It is a critical component in ensuring the resilience and reliability of a distributed system.
+
+Tyk's circuit breaker can be configured at the endpoint level, where it monitors the rate of failure responses (HTTP 500 or higher) received from the upstream service. If that failure rate exceeds the configured threshold, the circuit breaker will trip and Tyk will block further requests to that endpoint (returning `HTTP 503 Service temporarily unavailable`) until the end of a recovery (cooldown) time period.
+
+Tyk can trigger events when the circuit breaker trips and when it resets. These events can be used for monitoring, alerting, or automation of recovery processes.
{{< img src="/img/diagrams/diagram_docs_circuit-breakers@2x.png" alt="Circuit breaker example" >}}
-Tyk has a built-in circuit breaker pattern as a path-based option. Our circuit breaker is rate-based, so if a sample size `x` of `y` % requests fail, the breaker will trip. This triggers an event which you can hook into to perform corrective or logging action. For example, if `x = 10` and `y = 100` then your threshold percent is `10/100` % in a float range of `0 - 1`.
+## When to use a circuit breaker
-{{< note success >}}
-**Note**
+#### Protection of critical API endpoints
-The value of the samples have to be collected within a 10 sec window before they are evaluated. So for `10/100`, 100 requests have to be retrieved first before checking whether the conditions are met for the breaker to be tripped.
-{{< /note >}}
+Circuit breakers can be used to safeguard essential API endpoints from overloading, ensuring their availability and performance. By implementing circuit breakers, users can prevent these endpoints from being overwhelmed, maintaining their reliability and responsiveness.
-The Gateway will stop **all** inbound requests to that service for a pre-defined period of time (a recovery time-period). You can configure this recovery time-period using the `return_to_service_after` option in your API definition, or via the Dashboard.
+#### Handling temporary issues
-Once a circuit breaker has been tripped, the Tyk Gateway will return a 503 "Service temporarily unavailable" error for any calls to the API until the end of the recovery time-period.
+Circuit breakers can help handle temporary issues in the system, such as temporary outages or performance degradation, by opening and closing the circuit when conditions are unfavorable, allowing the system to recover and resume normal operation.
-During the recovery time-period, the Tyk Gateway will periodically issue requests to the upstream service to check whether the path has been restored. If the gateway detects that the path has been reconnected, the circuit breaker will be automatically reset and the `BreakerReset` event will be generated.
+#### Implementing retry logic
-This behaviour is described as the circuit breaker being "half-open"; if the desired behaviour is to enforce the full recovery time period (i.e. to unblock the path only after the `return_to_service_after` time period) then you can disable the half-open operation by setting `disable_half_open_state` to `true`.
+Circuit breakers can be used to automatically manage the retry of failed requests after a hold-off period, increasing the chances of successful execution.
-See [Configure with the API Definition](#configure-with-the-api-definition) or [Configure with the Dashboard](#configure-with-the-dashboard).
+#### Implementing fallback mechanisms
-The circuit breaker works across hosts (i.e. if you have multiple targets for an API, the sample is across **all** upstream requests).
+Circuit breakers can trigger alternative workflows or fallback mechanisms when the primary system fails, ensuring uninterrupted service delivery despite system failures.
-Circuit breakers are individual on a single host, they do not centralise or pool back-end data. This is for speed purposes. This means that in a load balanced environment where multiple Tyk nodes are used, some traffic can spill through as other nodes reach the sampling rate limit.
+## How the circuit breaker works
-#### Events
+Similarly to the circuit breaker in an electrical installation, Tyk's circuit breaker middleware monitors the flow and trips (breaks the connection) if it detects errors. Whilst the electrical circuit breaker monitors the flow of electricity and trips if it detects overcurrent (e.g. a short-circuit), Tyk's monitors the responses back from the upstream service and trips if it detects too many failures.
-When a circuit breaker trips, it can fire a `BreakerTriggered` [event type]({{< ref "/content/basic-config-and-security/report-monitor-trigger-events/event-types.md" >}}) which you can define actions for in the `event_handlers` section (see [Event Data]({{< ref "basic-config-and-security/report-monitor-trigger-events/event-data" >}}) and [Event Types]({{< ref "basic-config-and-security/report-monitor-trigger-events/event-types" >}}) for more information).
+From the perspective of the circuit breaker middleware, a failure is considered any response with HTTP status code `500` or above.
-{{< note success >}}
-**Note**
+The circuit breaker is rate-based, meaning that it counts the number of failure responses received in a rolling sample window and trips if the failure rate exceeds the configured threshold.
-The Dashboard supports the separate `BreakerTripped` and `BreakerReset` events, but not the combined `BreakerTriggered` event. See [Configure with the Dashboard](#configure-with-the-dashboard) for more details.
-{{< /note >}}
+The rolling sample window is set to 10 seconds and the circuit breaker is designed to trip only if a user-configurable minimum number of samples (requests) fail within the window period.
-```{.copyWrapper}
-event_handlers: {
- events: {
- BreakerTriggered: [
- {
- handler_name: "eh_web_hook_handler",
- handler_meta: {
- method: "POST",
- target_path: "http://posttestserver.com/post.php?dir=tyk-breaker",
- template_path: "templates/breaker_webhook.json",
- header_map: {
- "X-Tyk-Test-Header": "Tyk v1.BANANA"
- },
- event_timeout: 10
- }
- }
- ]
- }
- },
-```
-
-The status codes returned to the template are:
-
-```
-// BreakerTripped is sent when a breaker trips
-BreakerTripped = 0
-
-// BreakerReset is sent when a breaker resets
-BreakerReset = 1
-```
+Thus, if the _sample size_ is set to 100 and the _failure rate_ is set to 0.5 (50%) then the circuit breaker will trip only when there have been a minimum of 100 requests made in the past 10 seconds of which at least 50 have failed (returned an `HTTP 500` or higher error).
-{{< note success >}}
-**Note**
+Once the breaker has been tripped it will remain _open_, blocking calls to the endpoint until a configurable cooldown (or return-to-service) period has elapsed. While the breaker is _open_, requests to the endpoint will return `HTTP 503 Service temporarily unavailable`.
-If you are using the service discovery module, every time the breaker trips, Tyk will attempt to refresh the node list.
-{{< /note >}}
+### Half-open mode
+
+In some scenarios the upstream service might recover more quickly than the configured cooldown period. The middleware supports a _half-open_ mode that facilitates an early return-to-service so that API clients do not have to wait until the end of the cooldown before the circuit breaker is reset.
+
+In the _half-open_ mode, Tyk will periodically issue requests to the upstream service to check whether the path has been restored (while continuing to block client requests). If the Gateway detects that the path has been reconnected, the circuit breaker will be automatically reset (following the electrical circuit analogy, the circuit breaker is _closed_) and requests will be passed to the upstream again.
+
+### Configuring the circuit breaker
+The circuit breaker is configured using only three parameters:
+- sample size
+- error rate threshold
+- cooldown period
+The threshold is a ratio of the number of failures received in the sample window. For example, if the sample window size is 100 requests and you wish to trip the circuit breaker if there are 15 failures in any 100 requests, the threshold should be set to `15/100 = 0.15`.
-## Configure with the API Definition
+The cooldown period is the time that the circuit breaker will remain _open_ after the error rate threshold has been met and the breaker has been tripped.
-To enable the breaker in your API Definition, you will need to add a new section to your versions' `extended_paths` list:
+There is also an option to enable or disable the _half-open_ state if this would be damaging to your system.
-```{.copyWrapper}
-"circuit_breakers": [
- {
- "path": "get",
- "method": "GET",
- "threshold_percent": 0.5,
- "samples": 5,
- "return_to_service_after": 60,
- "disable_half_open_state": false
- }
-]
-```
+{{< note success >}}
+**Note**
+
+If you are using the Service Discovery module, every time the breaker trips, Tyk will attempt to refresh the Gateway list.
+{{< /note >}}
-* `path`: The path to match on.
-* `method`: The method to match on.
-* `threshold_percent`: The percentage of requests that can error before the breaker is tripped. This must be a value between 0.0 and 1.0.
-* `samples`: The number of samples to take for a circuit breaker window.
-* `return_to_service_after`: The cool-down period of the breaker to return to service (seconds).
-* `disable_half_open_state`: By default the Tyk circuit breaker has enabled the half-open state, if the desired behavior is to only check after the time configured in `return_to_service_after` is consumed then you can disable this by this option to `true`.
+### Using the circuit breaker with multiple upstream hosts
-## Configure with the Dashboard
+The circuit breaker works at the endpoint level independent of the number of upstream hosts are servicing the requests. Thus, if you have multiple upstream targets for an API, the sample and failure counts are accumulated across **all** upstream requests. If the failure rate exceeds the threshold, the circuit breaker will trip even if only some of your upstream hosts are failing. Operating in _half-open_ mode will of course cause the breaker to reset if a responsive upstream receives a request, but the `BreakerTripped` (or `BreakerTriggered`) event should alert you to the fact that at least one host is failing.
-To set up a circuit breaker on a path for your API, add a new Endpoint in the **Endpoint Designer** section of your API and then select the **Circuit Breaker** plugin:
+### Using the circuit breaker with multiple Tyk Gateways
+Circuit breakers operate on a single Tyk Gateway, they do not centralise or pool back-end data. This ensures optimum speed of response and resilience to Gateway failure. Subsequently, in a load balanced environment where multiple Tyk Gateways are used, some traffic can spill through even after the circuit breaker has tripped on one Gateway as other Gateways continue to serve traffic to the upstream before their own breakers trip.
-{{< img src="/img/2.10/circuit_breaker.png" alt="Plugin dropdown list" >}}
+### Circuit breaker events
-Once the plugin is active, you can set up the various configurations options for the breaker in the drawer by clicking on it:
+The circuit breaker automatically controls the flow of requests to the upstream services quickly and efficiently, but it is equally important to alert you to the fact that there is an issue and to confirm when traffic will recommence once the issue is resolved. Tyk's [Event]({{< ref "basic-config-and-security/report-monitor-trigger-events" >}}) system provides the method by which the circuit breaker can alert you to these occurrences.
+- When the circuit breaker trips (from closed to open), Tyk will generate a `BreakerTripped` event
+- When the breaker resets (from open to closed), whether at the end of the cooldown period or if connection is restored while in _half-open_ mode, Tyk will generate a `BreakerReset` event
+- In addition to these, whenever the circuit breaker changes state (from closed to open or vice versa), Tyk will generate a `BreakerTriggered` event
+
+For the generic `BreakerTriggered` event, the state change will be indicated in the `Status` field in the webhook template as follows:
+- when a breaker trips `CircuitEvent = 0`
+- when a breaker resets `CircuitEvent = 1`
-{{< img src="/img/2.10/ciruit_breaker_settings.png" alt="Circuit breaker configuration form" >}}
+### API-level circuit breaker
-* **Trigger threshold percentage**: The percentage of requests that can error before the breaker is tripped, this must be a value between 0.0 and 1.0.
-* **Sample size (requests)**: The number of samples to take for a circuit breaker window.
-* **Return to service in (s)**: The cool-down period of the breaker to return to service (seconds).
+Tyk does not have an API-level circuit breaker that can be applied across all endpoints. If you are using the Tyk Dashboard, however, then you are able to use an [Open Policy Agent]({{< ref "tyk-dashboard/open-policy-agent.md" >}}) to append a circuit breaker to every API/Service using the regex `.*` path.
-The Dashboard supports the separate `BreakerTripped` and `BreakerReset` events, but not the combined `BreakerTriggered` [event type]({{< ref "/content/basic-config-and-security/report-monitor-trigger-events/event-types.md" >}}). You should use **API Designer > Advanced Options** to add a Webhook plugin to your endpoint for each event.
+
-{{< img src="/img/dashboard/system-management/webhook-breaker.png" alt="Webhook events" >}}
+If you're using Tyk OAS APIs, then you can find details and examples of how to configure the circuit breaker middleware [here]({{< ref "product-stack/tyk-gateway/middleware/circuit-breaker-tyk-oas" >}}).
-## Global Circuit Breaker
+If you're using Tyk Classic APIs, then you can find details and examples of how to configure the circuit breaker middleware [here]({{< ref "product-stack/tyk-gateway/middleware/circuit-breaker-tyk-classic" >}}).
-We have no global circuit breaker at the moment. However, if you have the Tyk Dashboard, then you are able to use an [Open Policy Agent]({{< ref "/content/tyk-dashboard/open-policy-agent.md" >}}) to append a circuit breaker to every API/Service using the regex `.*` path.
+
diff --git a/tyk-docs/content/planning-for-production/ensure-high-availability/enforced-timeouts.md b/tyk-docs/content/planning-for-production/ensure-high-availability/enforced-timeouts.md
index 4a58e0fddd..6b9c714fc7 100755
--- a/tyk-docs/content/planning-for-production/ensure-high-availability/enforced-timeouts.md
+++ b/tyk-docs/content/planning-for-production/ensure-high-availability/enforced-timeouts.md
@@ -3,43 +3,52 @@ date: 2017-03-24T11:07:33Z
title: Enforced Timeouts
tags: ["High Availability", "SLAs", "Uptime", "Monitoring", "Enforced Timeouts"]
description: "How to enforce timeouts to keep your Tyk installation responding"
-menu:
- main:
- parent: "Ensure High Availability"
-weight: 4
---
-Enforced timeouts are a good way to ensure that your service always responds within a given amount of time, even if a long-running process hangs. This is important in high-availability systems where response performance is crucial so errors can be dealt with cleanly.
+In any system, a task or operation takes a certain period of time to complete. When a client makes a request to the Tyk Gateway, it will be dependent upon the responsiveness of the upstream service before it can continue. If the upstream service is suffering from resource overload or congestion the response may be returned too late leading to unacceptable experience for the end user or even to instability in the system.
-{{< note success >}}
-**Note**
+Tyk's Enforced Timeout middleware can be used to apply a maximum time that the Gateway will wait for a response before it terminates (or times out) the request. If the timeout expires, then Tyk will notify the client with an `HTTP 504 Gateway Timeout` error.
-If you are using the service discovery option, hard timeouts will force the service discovery module to refresh the host / host list.
-{{< /note >}}
+This feature helps to maintain system stability and prevents unresponsive or long-running tasks from affecting the overall performance of the system. The enforced timeout can be customised and configured to suit specific requirements, providing control over resource allocation and ensuring optimal system functionality.
+
+## When to use an enforced timeout
+
+#### Resource management
+
+The enforced timeout can be implemented to manage system resources efficiently, particularly in high-traffic environments, preventing long-running tasks from monopolising resources, ensuring fair distribution and optimal performance.
+
+#### Task prioritisation
+
+Prioritising critical tasks by setting timeouts based on their expected time-to-complete helps to ensure that essential tasks are completed by reducing the impact of non-responsive upstream services.
+#### Security measures
-### Enabling enforced timeouts in API Definitons
+Limiting task durations can help protect against potential security breaches or malicious activities by setting time constraints on user sessions or API requests.
-To enable an enforced timeout on a path, you must add to your versions' `extended_paths` section:
+#### Time-sensitive operations
-```{.copyWrapper}
-extended_paths: {
- ...
- transform_response_headers: [],
- hard_timeouts: [{
- path: "delay/5",
- method: "GET",
- timeout: 3
-}]
-}
-```
+For time-sensitive tasks, enforced timeouts can guarantee timely completion and avoid delays or missed deadlines.
-### Enabling enforced timeouts in the Tyk Dashboard API Designer
+## How the enforced timeout middleware works
+
+The enforced timeout middleware is enabled and configured at the endpoint level.
+
+The configuration is very simple, the only option being the duration of the timeout (which is declared in seconds) after which the upstream request will be terminated and an `HTTP 504 Gateway Timeout` error returned to the client.
+
+{{< note success >}}
+**Note**
+
+If you are using the Service Discovery option, if an enforced timeout is triggered, the service discovery module will refresh the host / host list.
+{{< /note >}}
-To enable an enforced timeout on an endpoint, select **Enforced timeout** plugin from the **Plugins** drop-down list:
+
-{{< img src="/img/2.10/enforced_breakout.png" alt="Plugin dropdown" >}}
+If you're using Tyk OAS APIs, then you can find details and examples of how to configure the enforced timeout middleware [here]({{< ref "product-stack/tyk-gateway/middleware/enforced-timeout-tyk-oas" >}}).
-Then enter the enforced timeout in seconds for the endpoint:
+If you're using Tyk Classic APIs, then you can find details and examples of how to configure the enforced timeout middleware [here]({{< ref "product-stack/tyk-gateway/middleware/enforced-timeout-tyk-classic" >}}).
-{{< img src="/img/2.10/enforced_timeouts_settings.png" alt="Enforced timeout configuration" >}}
+
diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/.placeholder b/tyk-docs/content/product-stack/tyk-gateway/middleware/.placeholder
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/circuit-breaker-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/circuit-breaker-tyk-classic.md
new file mode 100644
index 0000000000..a4419dbbfb
--- /dev/null
+++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/circuit-breaker-tyk-classic.md
@@ -0,0 +1,71 @@
+---
+title: Using the Circuit Breaker middleware with Tyk Classic APIs
+date: 2024-01-19
+description: "Using the Circuit Breaker with Tyk Classic APIs"
+tags: ["circuit breaker", "middleware", "per-endpoint", "Tyk Classic"]
+---
+
+Tyk's [circuit breaker]({{< ref "planning-for-production/ensure-high-availability/circuit-breakers" >}}) middleware is configured at the endpoint level, where it monitors the rate of failure responses (HTTP 500 or higher) received from the upstream service. If that failure rate exceeds the configured threshold, the circuit breaker will trip and Tyk will block further requests to that endpoint (returning `HTTP 503 Service temporarily unavailable`) until the end of a recovery (cooldown) time period.
+
+When working with Tyk Classic APIs the circuit breaker is configured in the Tyk Classic API Definition. You can do this via the Tyk Dashboard API or in the API Designer.
+
+If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/circuit-breaker-tyk-oas" >}}) page.
+
+## Configuring the Circuit Breaker in the Tyk Classic API Definition
+
+To configure the circuit breaker you must add a new `circuit_breakers` object to the `extended_paths` section of your API definition, with the following configuration:
+- `path`: the endpoint path
+- `method`: the endpoint HTTP method
+- `threshold_percent`: the proportion of requests that can error before the breaker is tripped, this must be a value between 0.0 and 1.0
+- `samples`: the minimum number of requests that must be received during the rolling sampling window before the circuit breaker can trip
+- `return_to_service_after`: the period for which the breaker will remain _open_ after being tripped before returning to service (seconds)
+- `disable_half_open_state`: by default the Tyk circuit breaker will operate in [half-open mode]({{< ref "planning-for-production/ensure-high-availability/circuit-breakers#half-open-mode" >}}) when working with Tyk Classic APIs, set this to `true` if you want Tyk to wait the full cooldown period before closing the circuit
+
+For example:
+```json {linenos=true, linenostart=1}
+{
+ "circuit_breakers": [
+ {
+ "path": "status/200",
+ "method": "GET",
+ "threshold_percent": 0.5,
+ "samples": 10,
+ "return_to_service_after": 60,
+ "disable_half_open_state": false
+ }
+ ]
+}
+```
+In this example the circuit breaker has been configured to monitor HTTP `GET` requests to the `/status/200` endpoint. It will configure a sampling window (`samples`) of 10 requests and calculate the ratio of failed requests (those returning HTTP 500 or above) within that window. If the ratio of failed requests exceeds 50% (`threshold_percent = 0.5`) then the breaker will be tripped. After it has tripped, the circuit breaker will remain _open_ for 60 seconds (`return_to_service_after`). The circuit breaker will operate in _half-open_ mode (`disable_half_open_state = false`) so when _open_, Tyk will periodically poll the upstream service to test if it has become available again.
+
+When the breaker has tripped, it will return `HTTP 503 Service temporarily unavailable` in response to any calls to `GET /status/200`.
+
+## Configuring the Circuit Breaker in the API Designer
+
+You can use the API Designer in the Tyk Dashboard to configure the circuit breaker middleware for your Tyk Classic API by following these steps.
+
+#### Step 1: Add an endpoint for the path and select the Circuit Breaker plugin
+
+From the **Endpoint Designer** add an endpoint that matches the path for which you want to deploy the circuit breaker. Select the **Circuit Breaker** plugin.
+
+{{< img src="/img/2.10/circuit_breaker.png" alt="Plugin dropdown list" >}}
+
+#### Step 2: Configure the circuit breaker
+
+You can set up the various configurations options for the breaker in the drawer by clicking on it:
+
+{{< img src="/img/2.10/ciruit_breaker_settings.png" alt="Circuit breaker configuration form" >}}
+
+- **Trigger threshold percentage**: The percentage of requests that can error before the breaker is tripped, this must be a value between 0.0 and 1.0
+- **Sample size (requests)**: The number of samples to take for a circuit breaker window
+- **Return to service in (s)**: The cool-down period of the breaker to return to service (seconds)
+
+#### Step 3: Save the API
+
+Use the *save* or *create* buttons to save the changes and make the circuit breaker active.
+
+#### Step 4: Optionally configure webhooks to respond to the circuit breaker events
+
+The Dashboard supports the separate `BreakerTripped` and `BreakerReset` events, but not the combined `BreakerTriggered` [event type]({{< ref "basic-config-and-security/report-monitor-trigger-events/event-types" >}}). You should use **API Designer > Advanced Options** to add a Webhook plugin to your endpoint for each event.
+
+{{< img src="/img/dashboard/system-management/webhook-breaker.png" alt="Webhook events" >}}
\ No newline at end of file
diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/circuit-breaker-tyk-oas.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/circuit-breaker-tyk-oas.md
new file mode 100644
index 0000000000..a3cc6fc3f7
--- /dev/null
+++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/circuit-breaker-tyk-oas.md
@@ -0,0 +1,124 @@
+---
+title: Using the Circuit Breaker middleware with Tyk OAS APIs
+date: 2024-01-19
+description: "Using the Circuit Breaker with Tyk OAS APIs"
+tags: ["circuit breaker", "middleware", "per-endpoint", "Tyk OAS"]
+---
+
+Tyk's [circuit breaker]({{< ref "planning-for-production/ensure-high-availability/circuit-breakers" >}}) middleware is configured at the endpoint level, where it monitors the rate of failure responses (HTTP 500 or higher) received from the upstream service. If that failure rate exceeds the configured threshold, the circuit breaker will trip and Tyk will block further requests to that endpoint (returning `HTTP 503 Service temporarily unavailable`) until the end of a recovery (cooldown) time period.
+
+When working with Tyk OAS APIs the circuit breaker is configured in the [Tyk OAS API Definition]({{< ref "tyk-apis/tyk-gateway-api/oas/x-tyk-oas-doc#operation" >}}). You can do this via the Tyk Dashboard API or in the API Designer.
+
+If you're using the legacy Tyk Classic APIs, then check out the [Tyk Classic]({{< ref "product-stack/tyk-gateway/middleware/circuit-breaker-tyk-classic" >}}) page.
+
+## Configuring the Circuit Breaker in the Tyk OAS API Definition
+
+The design of the Tyk OAS API Definition takes advantage of the `operationId` defined in the OpenAPI Document that declares both the path and method for which the middleware should be added. Endpoint `paths` entries (and the associated `operationId`) can contain wildcards in the form of any string bracketed by curly braces, for example `/status/{code}`. These wildcards are so they are human readable and do not translate to variable names. Under the hood, a wildcard translates to the “match everything” regex of: `(.*)`.
+
+The circuit breaker middleware (`circuitBreaker`) can be added to the `operations` section of the Tyk OAS Extension (`x-tyk-api-gateway`) in your Tyk OAS API Definition for the appropriate `operationId` (as configured in the `paths` section of your OpenAPI Document).
+
+The `circuitBreaker` object has the following configuration:
+- `enabled`: enable the middleware for the endpoint
+- `threshold`: the proportion of requests that can error before the breaker is tripped, this must be a value between 0.0 and 1.0
+- `sampleSize`: the minimum number of requests that must be received during the rolling sampling window before the circuit breaker can trip
+- `coolDownPeriod`: the period for which the breaker will remain _open_ after being tripped before returning to service (seconds)
+- `halfOpenStateEnabled`: if set to `true` then the circuit breaker will operate in [half-open mode]({{< ref "planning-for-production/ensure-high-availability/circuit-breakers#half-open-mode" >}}) once it has been tripped
+
+```json {hl_lines=["39-45"],linenos=true, linenostart=1}
+{
+ "components": {},
+ "info": {
+ "title": "example-breaker",
+ "version": "1.0.0"
+ },
+ "openapi": "3.0.3",
+ "paths": {
+ "/status/200": {
+ "get": {
+ "operationId": "status/200get",
+ "responses": {
+ "200": {
+ "description": ""
+ }
+ }
+ }
+ }
+ },
+ "x-tyk-api-gateway": {
+ "info": {
+ "name": "example-breaker",
+ "state": {
+ "active": true
+ }
+ },
+ "upstream": {
+ "url": "http://httpbin.org/"
+ },
+ "server": {
+ "listenPath": {
+ "value": "/example-breaker/",
+ "strip": true
+ }
+ },
+ "middleware": {
+ "operations": {
+ "status/200get": {
+ "circuitBreaker": {
+ "enabled": true,
+ "threshold": 0.5,
+ "sampleSize": 10,
+ "coolDownPeriod": 60,
+ "halfOpenStateEnabled": true
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+In this example Tyk OAS API Definition the circuit breaker has been configured to monitor requests to the `GET /status/200` endpoint.
+
+It will configure a minimum number of 10 requests (`sampleSize`) that must be received during a 10 second period and calculate the ratio of failed requests (those returning `HTTP 500` or above) within that window.
+- if the ratio of failed requests exceeds 50% (`threshold = 0.5`) then the breaker will be tripped
+- after it has tripped, the circuit breaker will remain _open_ for 60 seconds (`coolDownPeriod`)
+- further requests to `GET /status/200` will return `HTTP 503 Service temporarily unavailable`
+- the circuit breaker will operate in _half-open_ mode (`halfOpenStateEnabled = true`) so when the threshold has been reached and the breaker is tripped, Tyk will periodically poll the upstream service to test if it has become available again
+
+The configuration above is a complete and valid Tyk OAS API Definition that you can import into Tyk to try out the circuit breaker.
+
+## Configuring the Circuit Breaker in the API Designer
+
+Adding the circuit breaker to your API endpoints is easy when using the API Designer in the Tyk Dashboard, simply follow these steps:
+
+#### Step 1: Add an endpoint
+
+From the **API Designer** add an endpoint that matches the path and method to which you want to apply the middleware.
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-no-endpoints.png" alt="Tyk OAS API Designer showing no endpoints created" >}}
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-add-endpoint.png" alt="Adding an endpoint to an API using the Tyk OAS API Designer" >}}
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-no-middleware.png" alt="Tyk OAS API Designer showing no middleware enabled on endpoint" >}}
+
+#### Step 2: Select the Circuit Breaker middleware
+
+Select **ADD MIDDLEWARE** and choose the **Circuit Breaker** middleware from the *Add Middleware* screen.
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-circuit-breaker.png" alt="Adding the Circuit Breaker middleware" >}}
+
+#### Step 3: Configure the middleware
+
+Set the circuit breaker configuration parameters so that Tyk can protect your upstream service if it experiences failure:
+- threshold failure rate for the proportion of requests that can error before the breaker is tripped (a value between 0.0 and 1.0)
+- the minimum number of requests that must be received during the rolling sampling window before the circuit breaker can trip
+- the cooldown period for which the breaker will remain _open_ after being tripped before returning to service (in seconds)
+- optionally enable [half-open mode]({{< ref "planning-for-production/ensure-high-availability/circuit-breakers#half-open-mode" >}}) for upstream services with variable recovery times
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-circuit-breaker-config.png" alt="Configuring the circuit breaker for the endpoint" >}}
+
+Select **ADD MIDDLEWARE** to apply the change to the middleware configuration.
+
+#### Step 4: Save the API
+
+Select **SAVE API** to apply the changes to your API.
diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/enforced-timeout-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/enforced-timeout-tyk-classic.md
new file mode 100644
index 0000000000..39d402e554
--- /dev/null
+++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/enforced-timeout-tyk-classic.md
@@ -0,0 +1,58 @@
+---
+title: Using the Enforced Timeout middleware with Tyk Classic APIs
+date: 2024-01-19
+description: "Using the Enforced Timeout with Tyk Classic APIs"
+tags: ["Enforced Timeouts", "middleware", "per-endpoint", "Tyk Classic"]
+---
+
+Tyk's [enforced timeout]({{< ref "planning-for-production/ensure-high-availability/enforced-timeouts" >}}) middleware is configured at the endpoint level, where it sets a limit on the response time from the upstream service. If the upstream takes too long to respond to a request, Tyk will terminate the request and return `504 Gateway Timeout` to the client.
+
+When working with Tyk Classic APIs the enforced timeout is configured in the Tyk Classic API Definition. You can do this via the Tyk Dashboard API or in the API Designer.
+
+If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/enforced-timeout-tyk-oas" >}}) page.
+
+## Configuring an enforced timeout in the Tyk Classic API Definition
+
+To configure an enforced timeout you must add a new `hard_timeouts` object to the `extended_paths` section of your API definition.
+
+It has the following configuration:
+- `path`: the endpoint path
+- `method`: the endpoint HTTP method
+- `timeout`: the duration of the upstream request timer
+
+For example:
+```json
+{
+ "hard_timeouts": [
+ {
+ "path": "/status/200",
+ "method": "GET",
+ "timeout": 3
+ }
+ ]
+}
+```
+
+In this example the enforced timeout has been configured to monitor requests to the `GET /status/200` endpoint. It will configure a timer that will expire (`timeout`) 3 seconds after the request is proxied to the upstream service.
+
+If the upstream response is not received before the expiry of the timer, that request will be terminated and Tyk will return `504 Gateway Timeout` to the client.
+
+## Configuring an enforced timeout in the API Designer
+
+You can use the API Designer in the Tyk Dashboard to configure the enforced timeout middleware for your Tyk Classic API by following these steps.
+
+#### Step 1: Add an endpoint for the path and select the Enforced Timeout plugin
+
+From the **Endpoint Designer** add an endpoint that matches the path for which you want to deploy the enforced timeout. Select the **Enforced timeout** plugin.
+
+{{< img src="/img/2.10/enforced_breakout.png" alt="Plugin dropdown" >}}
+
+#### Step 2: Configure the timeout
+
+Then enter the timeout to be enforced for the endpoint (in seconds):
+
+{{< img src="/img/2.10/enforced_timeouts_settings.png" alt="Enforced timeout configuration" >}}
+
+#### Step 3: Save the API
+
+Use the *save* or *create* buttons to save the changes and make the circuit breaker active.
diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/enforced-timeout-tyk-oas.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/enforced-timeout-tyk-oas.md
new file mode 100644
index 0000000000..094336f8f0
--- /dev/null
+++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/enforced-timeout-tyk-oas.md
@@ -0,0 +1,109 @@
+---
+title: Using the Enforced Timeout middleware with Tyk OAS APIs
+date: 2024-01-19
+description: "Using the Enforced Timeout with Tyk OAS APIs"
+tags: ["Enforced Timeouts", "middleware", "per-endpoint", "Tyk OAS"]
+---
+
+Tyk's [enforced timeout]({{< ref "planning-for-production/ensure-high-availability/enforced-timeouts" >}}) middleware is configured at the endpoint level, where it sets a limit on the response time from the upstream service. If the upstream takes too long to respond to a request, Tyk will terminate the request and return `504 Gateway Timeout` to the client.
+
+When working with Tyk OAS APIs the enforced timeout is configured in the [Tyk OAS API Definition]({{< ref "tyk-apis/tyk-gateway-api/oas/x-tyk-oas-doc#operation" >}}). You can do this via the Tyk Dashboard API or in the API Designer.
+
+If you're using the legacy Tyk Classic APIs, then check out the [Tyk Classic]({{< ref "product-stack/tyk-gateway/middleware/enforced-timeout-tyk-classic" >}}) page.
+
+## Configuring an enforced timeout in the Tyk OAS API Definition
+
+The design of the Tyk OAS API Definition takes advantage of the `operationId` defined in the OpenAPI Document that declares both the path and method for which the middleware should be added. Endpoint `paths` entries (and the associated `operationId`) can contain wildcards in the form of any string bracketed by curly braces, for example `/status/{code}`. These wildcards are so they are human readable and do not translate to variable names. Under the hood, a wildcard translates to the “match everything” regex of: `(.*)`.
+
+The circuit breaker middleware (`enforceTimeout`) can be added to the `operations` section of the Tyk OAS Extension (`x-tyk-api-gateway`) in your Tyk OAS API Definition for the appropriate `operationId` (as configured in the `paths` section of your OpenAPI Document).
+
+The `enforceTimeout` object has the following configuration:
+- `enabled`: enable the middleware for the endpoint
+- `value`: the duration of the upstream request timer
+
+For example:
+```json {hl_lines=["39-41"],linenos=true, linenostart=1}
+{
+ "components": {},
+ "info": {
+ "title": "example-timeout",
+ "version": "1.0.0"
+ },
+ "openapi": "3.0.3",
+ "paths": {
+ "/status/200": {
+ "get": {
+ "operationId": "status/200get",
+ "responses": {
+ "200": {
+ "description": ""
+ }
+ }
+ }
+ }
+ },
+ "x-tyk-api-gateway": {
+ "info": {
+ "name": "example-timeout",
+ "state": {
+ "active": true
+ }
+ },
+ "upstream": {
+ "url": "http://httpbin.org/"
+ },
+ "server": {
+ "listenPath": {
+ "value": "/example-timeout/",
+ "strip": true
+ }
+ },
+ "middleware": {
+ "operations": {
+ "status/200get": {
+ "enforceTimeout": {
+ "enabled": true,
+ "value": 3
+ }
+ }
+ }
+ }
+ }
+}
+ ```
+
+In this example Tyk OAS API definition, the enforced timeout has been configured to monitor requests to the `GET /status/200` endpoint. It will configure a timer that will expire (`timeout`) 3 seconds after the request is proxied to the upstream service. If the upstream response is not received before the expiry of the timer, that request will be terminated and Tyk will return `504 Gateway Timeout` to the client.
+
+The configuration above is a complete and valid Tyk OAS API Definition that you can import into Tyk to try out the enforced timeout.
+
+## Configuring an enforced timeout in the API Designer
+
+Adding the enforced timeout to your API endpoints is easy when using the API Designer in the Tyk Dashboard, simply follow these steps:
+
+#### Step 1: Add an endpoint
+
+From the **API Designer** add an endpoint that matches the path and method to which you want to apply the middleware.
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-no-endpoints.png" alt="Tyk OAS API Designer showing no endpoints created" >}}
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-add-endpoint.png" alt="Adding an endpoint to an API using the Tyk OAS API Designer" >}}
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-no-middleware.png" alt="Tyk OAS API Designer showing no middleware enabled on endpoint" >}}
+
+#### Step 2: Select the Enforce Timeout middleware
+
+Select **ADD MIDDLEWARE** and choose the **Enforce Timeout** middleware from the *Add Middleware* screen.
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-enforce-timeout.png" alt="Adding the Enforce Timeout middleware" >}}
+
+#### Step 3: Configure the middleware
+
+Set the timeout duration that you wish to enforce for requests to the endpoint.
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-enforce-timeout-config.png" alt="Configuring the enforced timeout for the endpoint" >}}
+
+Select **ADD MIDDLEWARE** to apply the change to the middleware configuration.
+
+#### Step 4: Save the API
+
+Select **SAVE API** to apply the changes to your API.
diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/request-header-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-header-tyk-classic.md
new file mode 100644
index 0000000000..87a8adf48d
--- /dev/null
+++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-header-tyk-classic.md
@@ -0,0 +1,139 @@
+---
+title: Using the Request Header Transform with Tyk Classic APIs
+date: 2024-01-20
+description: "Using the Request Header Transform middleware with Tyk Classic APIs"
+tags: ["Request Header Transform", "middleware", "per-endpoint","per-API", "Tyk Classic"]
+---
+
+Tyk's [request header transform]({{< ref "transform-traffic/request-headers" >}}) middleware enables you to append or delete headers on requests to your API endpoints before they are passed to your upstream service.
+
+There are two options for this:
+- API-level modification that is applied to all requests to the API
+- endpoint-level modification that is applied only to requests to a specific endpoint
+
+{{< note success >}}
+**Note**
+
+If both API-level and endpoint-level middleware are configured, the API-level transformation will be applied first.
+{{< /note >}}
+
+When working with Tyk Classic APIs the transformation is configured in the Tyk Classic API Definition. You can do this via the Tyk Dashboard API or in the API Designer.
+
+If you want to use dynamic data from context variables, you must [enable]({{< ref "context-variables#enabling-context-variables-for-use-with-tyk-classic-apis" >}}) context variables for the API to be able to access them from the request header transform middleware.
+
+If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/request-header-tyk-oas" >}}) page.
+
+## Configuring the Request Header Transform in the Tyk Classic API Definition
+
+The API-level and endpoint-level request header transforms have a common configuration but are configured in different sections of the API definition.
+
+#### API-level transform
+
+To **append** headers to all requests to your API (i.e. for all endpoints) you must add a new `global_headers` object to the `versions` section of your API definition. This contains a list of key:value pairs, being the names and values of the headers to be added to requests.
+
+To **delete** headers from all requests to your API, you must add a new `global_headers_remove` object to the `versions` section of the API definition. This contains a list of the names of existing headers to be removed from requests.
+
+For example:
+```json {hl_lines=["39-45"],linenos=true, linenostart=1}
+{
+ "version_data": {
+ "versions": {
+ "Default": {
+ "global_headers": {
+ "X-Static": "foobar",
+ "X-Request-ID":"$tyk_context.request_id",
+ "X-User-ID": "$tyk_meta.uid"
+ },
+ "global_headers_remove": [
+ "Auth_Id"
+ ]
+ }
+ }
+ },
+}
+```
+
+This configuration will add three new headers to each request:
+- `X-Static` with the value `foobar`
+- `X-Request-ID` with a dynamic value taken from the `request_id` [context variables]({{< ref "context-variables" >}})
+- `X-User-ID` with a dynamic value taken from the `uid` field in the [session metadata]({{< ref "getting-started/key-concepts/session-meta-data" >}})
+
+It will also delete one header (if present) from each request:
+- `Auth_Id`
+
+#### Endpoint-level transform
+
+To configure a transformation of the request header for a specific endpoint you must add a new `transform_headers` object to the `extended_paths` section of your API definition.
+
+It has the following configuration:
+- `path`: the endpoint path
+- `method`: the endpoint HTTP method
+- `delete_headers`: A list of the headers that should be deleted from the request
+- `add_headers`: A list of headers, in key:value pairs, that should be added to the request
+
+The `path` can contain wildcards in the form of any string bracketed by curly braces, for example `{user_id}`. These wildcards are so they are human readable and do not translate to variable names. Under the hood, a wildcard translates to the “match everything” regex of: `(.*)`.
+
+For example:
+```json
+{
+ "transform_headers": [
+ {
+ "path": "status/200",
+ "method": "GET",
+ "delete_headers": ["X-Static"],
+ "add_headers": {"X-Secret": "the-secret-key-is-secret"}
+ }
+ ]
+}
+```
+
+In this example the Request Header Transform middleware has been configured for HTTP `GET` requests to the `/status/200` endpoint. Any request received to that endpoint will have the `X-Static` header removed and the `X-Secret` header added, with the value set to `the-secret-key-is-secret`.
+
+#### Combining API-level and Endpoint-level transforms
+
+If the API-level transform in the previous [example]({{< ref "product-stack/tyk-gateway/middleware/request-header-tyk-classic#api-level-transform" >}}) is applied to the same API, then because the API-level transformation is performed first, the `X-Static` header will be added (by the API-level transform) and then removed (by the endpoint-level transform) such that the overall effect of the two transforms for a call to `GET /status/200` would be to add three headers:
+- `X-Request-ID`
+- `X-User-ID`
+- `X-Secret`
+
+and to remove one:
+- `Auth_Id`
+
+## Configuring the Request Header Transform in the API Designer
+
+You can use the API Designer in the Tyk Dashboard to configure the request header transform middleware for your Tyk Classic API by following these steps.
+
+### API-level transform
+
+Configuring the API-level request header transform middleware is very simple when using the Tyk Dashboard.
+
+In the Endpoint Designer you should select the **Global Version Settings** and ensure that you have selected the **Request Headers** tab:
+
+{{< img src="/img/2.10/global_settings_modify_headers.png" alt="Global version settings" >}}
+
+Note that you must click **ADD** to add a header to the list (for appending or deletion).
+
+### Endpoint-level transform
+
+##### Step 1: Add an endpoint for the path and select the Header Transform plugin
+
+From the **Endpoint Designer** add an endpoint that matches the path for which you want to perform the transformation. Select the **Modify Headers** plugin.
+
+{{< img src="/img/2.10/modify_headers.png" alt="Endpoint designer" >}}
+
+##### Step 2: Select the "Request" tab
+
+This ensures that this will only be applied to inbound requests.
+
+{{< img src="/img/2.10/modify_headers1.png" alt="Request tab" >}}
+
+##### Step 3: Declare the headers to be modified
+
+Select the headers to delete and insert using the provided fields. You need to click **ADD** to ensure they are added to the list.
+
+{{< img src="/img/2.10/modify_headers2.png" alt="Header transforms" >}}
+
+##### Step 4: Save the API
+Use the *save* or *create* buttons to save the changes and make the transform middleware active.
+
+
diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/request-header-tyk-oas.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-header-tyk-oas.md
new file mode 100644
index 0000000000..544859e329
--- /dev/null
+++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-header-tyk-oas.md
@@ -0,0 +1,232 @@
+---
+title: Using the Request Header Transform with Tyk OAS APIs
+date: 2024-01-20
+description: "Using the Request Header Transform middleware with Tyk OAS APIs"
+tags: ["Request Header Transform", "middleware", "per-endpoint", "Tyk OAS"]
+---
+
+Tyk's [request header transform]({{< ref "transform-traffic/request-headers" >}}) middleware enables you to append or delete headers on requests to your API endpoints before they are passed to your upstream service.
+
+There are two options for this:
+- API-level modification that is applied to all requests to the API
+- endpoint-level modification that is applied only to requests to a specific endpoint
+
+{{< note success >}}
+**Note**
+
+If both API-level and endpoint-level middleware are configured, the API-level transformation will be applied first.
+{{< /note >}}
+
+When working with Tyk OAS APIs the transformation is configured in the [Tyk OAS API Definition]({{< ref "tyk-apis/tyk-gateway-api/oas/x-tyk-oas-doc#operation" >}}). You can do this via the Tyk Dashboard API or in the API Designer.
+
+If you're using the legacy Tyk Classic APIs, then check out the [Tyk Classic]({{< ref "product-stack/tyk-gateway/middleware/request-header-tyk-classic" >}}) page.
+
+## Configuring the Request Header Transform in the Tyk OAS API Definition
+
+The API-level and endpoint-level request header transforms are configured in different sections of the API definition, though have a common configuration.
+
+### API-level transform
+
+To append headers to, or delete headers from, all requests to your API (i.e. for all endpoints) you must add a new `transformRequestHeaders` object to the `middleware.global` section of the Tyk OAS Extension (`x-tyk-api-gateway`) in your Tyk OAS API Definition.
+
+You only need to enable the middleware (set `enabled:true`) and then configure the details of headers to `add` and those to `remove`.
+
+For example:
+```json {hl_lines=["38-56"],linenos=true, linenostart=1}
+{
+ "components": {},
+ "info": {
+ "title": "example-request-header",
+ "version": "1.0.0"
+ },
+ "openapi": "3.0.3",
+ "paths": {
+ "/status/200": {
+ "get": {
+ "operationId": "status/200get",
+ "responses": {
+ "200": {
+ "description": ""
+ }
+ }
+ }
+ }
+ },
+ "x-tyk-api-gateway": {
+ "info": {
+ "name": "example-request-header",
+ "state": {
+ "active": true
+ }
+ },
+ "upstream": {
+ "url": "http://httpbin.org/"
+ },
+ "server": {
+ "listenPath": {
+ "value": "/example-request-header/",
+ "strip": true
+ }
+ },
+ "middleware": {
+ "global": {
+ "transformRequestHeaders": {
+ "enabled": true,
+ "remove": [
+ "Auth_Id"
+ ],
+ "add": [
+ {
+ "name": "X-Static",
+ "value": "foobar"
+ },
+ {
+ "name": "X-Request-ID",
+ "value": "$tyk_context.request_id"
+ },
+ {
+ "name": "X-User-ID",
+ "value": "$tyk_meta.uid"
+ }
+ ]
+ }
+ }
+ }
+ }
+}
+```
+
+This configuration will add three new headers to each request:
+- `X-Static` with the value `foobar`
+- `X-Request-ID` with a dynamic value taken from the `request_id` [context variables]({{< ref "context-variables" >}})
+- `X-User-ID` with a dynamic value taken from the `uid` field in the [session metadata]({{< ref "getting-started/key-concepts/session-meta-data" >}})
+
+It will also delete one header (if present) from each request:
+- `Auth_Id`
+
+The configuration above is a complete and valid Tyk OAS API Definition that you can import into Tyk to try out the API-level request header transform.
+
+### Endpoint-level transform
+
+The design of the Tyk OAS API Definition takes advantage of the `operationId` defined in the OpenAPI Document that declares both the path and method for which the middleware should be added. Endpoint `paths` entries (and the associated `operationId`) can contain wildcards in the form of any string bracketed by curly braces, for example `/status/{code}`. These wildcards are so they are human readable and do not translate to variable names. Under the hood, a wildcard translates to the “match everything” regex of: `(.*)`.
+
+The request header transform middleware (`transformRequestHeaders`) can be added to the `operations` section of the Tyk OAS Extension (`x-tyk-api-gateway`) in your Tyk OAS API Definition for the appropriate `operationId` (as configured in the `paths` section of your OpenAPI Document).
+
+The `transformRequestHeaders` object has the following configuration:
+- `enabled`: enable the middleware for the endpoint
+- `add`: a list of headers, in key:value pairs, to be appended to the request
+- `remove`: a list of headers to be deleted from the request (if present)
+
+For example:
+```json {hl_lines=["39-50"],linenos=true, linenostart=1}
+{
+ "components": {},
+ "info": {
+ "title": "example-request-header",
+ "version": "1.0.0"
+ },
+ "openapi": "3.0.3",
+ "paths": {
+ "/status/200": {
+ "get": {
+ "operationId": "status/200get",
+ "responses": {
+ "200": {
+ "description": ""
+ }
+ }
+ }
+ }
+ },
+ "x-tyk-api-gateway": {
+ "info": {
+ "name": "example-request-header",
+ "state": {
+ "active": true
+ }
+ },
+ "upstream": {
+ "url": "http://httpbin.org/"
+ },
+ "server": {
+ "listenPath": {
+ "value": "/example-request-header/",
+ "strip": true
+ }
+ },
+ "middleware": {
+ "operations": {
+ "status/200get": {
+ "transformRequestHeaders": {
+ "enabled": true,
+ "remove": [
+ "X-Static"
+ ],
+ "add": [
+ {
+ "name": "X-Secret",
+ "value": "the-secret-key-is-secret"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+In this example the Request Header Transform middleware has been configured for requests to the `GET /status/200` endpoint. Any request received to that endpoint will have the `X-Static` header removed and the `X-Secret` header added, with the value set to `the-secret-key-is-secret`.
+
+The configuration above is a complete and valid Tyk OAS API Definition that you can import into Tyk to try out the endpoint-level request header transform.
+
+### Combining API-level and Endpoint-level transforms
+
+If the API-level transform in the previous [example]({{< ref "product-stack/tyk-gateway/middleware/request-header-tyk-oas#api-level-transform" >}}) is applied to the same API, then because the API-level transformation is performed first, the `X-Static` header will be added (by the API-level transform) and then removed (by the endpoint-level transform) such that the overall effect of the two transforms for a call to `GET /status/200` would be to add three headers:
+ - `X-Request-ID`
+ - `X-User-ID`
+ - `X-Secret`
+
+and to remove one:
+ - `Auth_Id`
+
+## Configuring the Request Header Transform in the API Designer
+
+Adding and configuring the transforms to your API endpoints is easy when using the API Designer in the Tyk Dashboard, simply follow these steps:
+
+### Adding an API-level transform
+
+From the **API Designer** on the **Settings** tab, after ensuring that you are in *edit* mode, toggle the switch to **Enable Transform request headers** in the **Middleware** section:
+{{< img src="/img/dashboard/api-designer/tyk-oas-request-header-api-level.png" alt="Tyk OAS API Designer showing API-level Request Header Transform" >}}
+
+Then select **NEW HEADER** as appropriate to add or remove a header from API requests. You can add or remove multiple headers by selecting **ADD HEADER** to add another to the list:
+{{< img src="/img/dashboard/api-designer/tyk-oas-request-header-api-new-header.png" alt="Configuring the API-level Request Header Transform in Tyk OAS API Designer" >}}
+
+### Adding an endpoint level transform
+
+#### Step 1: Add an endpoint
+
+From the **API Designer** add an endpoint that matches the path and method to which you want to apply the middleware.
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-no-endpoints.png" alt="Tyk OAS API Designer showing no endpoints created" >}}
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-add-endpoint.png" alt="Adding an endpoint to an API using the Tyk OAS API Designer" >}}
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-no-middleware.png" alt="Tyk OAS API Designer showing no middleware enabled on endpoint" >}}
+
+##### Step 2: Select the Request Header Transform middleware
+Select **ADD MIDDLEWARE** and choose the **Request Header Transform** middleware from the *Add Middleware* screen.
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-request-header.png" alt="Adding the Request Header Transform middleware" >}}
+
+##### Step 3: Configure header transformation
+Select **NEW HEADER** to configure a header to be added to or removed from the request.
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-request-header-added.png" alt="Configuring the Request Header transformation" >}}
+
+You can add multiple headers to either list by selecting **NEW HEADER** again.
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-request-header-new.png" alt="Adding another header to the transformation" >}}
+
+##### Step 4: Save the API
+Select **ADD MIDDLEWARE** to save the middleware configuration. Remember to select **SAVE API** to apply the changes.
\ No newline at end of file
diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/request-method-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-method-tyk-classic.md
new file mode 100644
index 0000000000..7ef3949195
--- /dev/null
+++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-method-tyk-classic.md
@@ -0,0 +1,60 @@
+---
+title: Using the Request Method Transform with Tyk Classic APIs
+date: 2024-01-20
+description: "Using the Request Method Transform middleware with Tyk Classic APIs"
+tags: ["Request Method Transform", "middleware", "per-endpoint", "Tyk Classic"]
+---
+
+Tyk's [request method transform]({{< ref "advanced-configuration/transform-traffic/request-method-transform" >}}) middleware is configured at the endpoint level, where it modifies the HTTP method used in the request to a configured value.
+
+When working with Tyk Classic APIs the transformation is configured in the Tyk Classic API Definition. You can do this via the Tyk Dashboard API or in the API Designer.
+
+If you're using the newer Tyk OAS APIs, then check out the [Tyk OAS]({{< ref "product-stack/tyk-gateway/middleware/request-method-tyk-oas" >}}) page.
+
+## Configuring a Request Method Transform in the Tyk Classic API Definition
+
+To configure a transformation of the request method you must add a new `method_transforms` object to the `extended_paths` section of your API definition.
+
+It has the following configuration:
+- `path`: The path to match on
+- `method`: The method to match on
+- `to_method`: The new HTTP method to which the request should be transformed
+
+All standard HTTP methods are supported: `GET`, `PUT`, `POST`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`.
+
+For example:
+```json
+{
+ "method_transforms": [
+ {
+ "path": "/status/200",
+ "method": "GET",
+ "to_method": "POST"
+ }
+ ]
+}
+```
+
+In this example the Request Method Transform middleware has been configured for HTTP `GET` requests to the `/status/200` endpoint. Any request received to that endpoint will be modified to `POST /status/200`.
+
+## Configuring a Request Method Transform in the API Designer
+
+You can use the API Designer in the Tyk Dashboard to configure the request method transform middleware for your Tyk Classic API by following these steps.
+
+### Using the Dashboard
+
+#### Step 1: Add an endpoint for the path and select the Method Transform plugin
+
+From the **Endpoint Designer** add an endpoint that matches the path for which you want to perform the transformation. Select the **Method Transform** plugin.
+
+{{< img src="/img/2.10/method_transform.png" alt="Method Transform" >}}
+
+#### Step 2: Configure the transform
+
+Then select the HTTP method to which you wish to transform the request.
+
+{{< img src="/img/2.10/method_transform2.png" alt="Method Path" >}}
+
+#### Step 3: Save the API
+
+Use the *save* or *create* buttons to save the changes and make the transform middleware active.
\ No newline at end of file
diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/request-method-tyk-oas.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-method-tyk-oas.md
new file mode 100644
index 0000000000..9488b19b89
--- /dev/null
+++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-method-tyk-oas.md
@@ -0,0 +1,107 @@
+---
+title: Using the Request Method Transform with Tyk OAS APIs
+date: 2024-01-20
+description: "Using the Request Method Transform middleware with Tyk OAS APIs"
+tags: ["Request Method Transform", "middleware", "per-endpoint", "Tyk OAS"]
+---
+
+Tyk's [request method transform]({{< ref "advanced-configuration/transform-traffic/request-method-transform" >}}) middleware is configured at the endpoint level, where it modifies the HTTP method used in the request to a configured value.
+
+When working with Tyk OAS APIs the transformation is configured in the [Tyk OAS API Definition]({{< ref "tyk-apis/tyk-gateway-api/oas/x-tyk-oas-doc#operation" >}}). You can do this via the Tyk Dashboard API or in the API Designer.
+
+If you're using the legacy Tyk Classic APIs, then check out the [Tyk Classic]({{< ref "product-stack/tyk-gateway/middleware/request-method-tyk-classic" >}}) page.
+
+## Configuring the Request Method Transform in the Tyk OAS API Definition
+
+The request method transform middleware (`transformRequestMethod`) can be added to the `operations` section of the Tyk OAS Extension (`x-tyk-api-gateway`) in your Tyk OAS API Definition for the appropriate `operationId` (as configured in the `paths` section of your OpenAPI Document). Endpoint `paths` entries (and the associated `operationId`) can contain wildcards in the form of any string bracketed by curly braces, for example `/status/{code}`. These wildcards are so they are human readable and do not translate to variable names. Under the hood, a wildcard translates to the “match everything” regex of: `(.*)`.
+
+You only need to enable the middleware (set `enabled:true`) and then configure `toMethod` as the new HTTP method to which the request should be transformed. The design of the Tyk OAS API Definition takes advantage of the `operationId` defined in the OpenAPI Document that declares both the path and method for which the method should be transformed.
+
+All standard HTTP methods are supported: `GET`, `PUT`, `POST`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`.
+
+For example:
+```json {hl_lines=["39-41"],linenos=true, linenostart=1}
+{
+ "components": {},
+ "info": {
+ "title": "example-request-method",
+ "version": "1.0.0"
+ },
+ "openapi": "3.0.3",
+ "paths": {
+ "/status/200": {
+ "get": {
+ "operationId": "status/200get",
+ "responses": {
+ "200": {
+ "description": ""
+ }
+ }
+ }
+ }
+ },
+ "x-tyk-api-gateway": {
+ "info": {
+ "name": "example-request-method",
+ "state": {
+ "active": true
+ }
+ },
+ "upstream": {
+ "url": "http://httpbin.org/"
+ },
+ "server": {
+ "listenPath": {
+ "value": "/example-request-method/",
+ "strip": true
+ }
+ },
+ "middleware": {
+ "operations": {
+ "status/200get": {
+ "transformRequestMethod": {
+ "enabled": true,
+ "toMethod": "POST"
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+In this example the Request Method Transform middleware has been configured for requests to the `GET /status/200` endpoint. Any request received to that endpoint will be modified to `POST /status/200`.
+
+The configuration above is a complete and valid Tyk OAS API Definition that you can import into Tyk to try out the request method transform.
+
+## Configuring the Request Method Transform in the API Designer
+
+Adding the transform to your API endpoints is easy when using the API Designer in the Tyk Dashboard, simply follow these steps:
+
+#### Step 1: Add an endpoint
+
+From the **API Designer** add an endpoint that matches the path and method to which you want to apply the middleware.
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-no-endpoints.png" alt="Tyk OAS API Designer showing no endpoints created" >}}
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-add-endpoint.png" alt="Adding an endpoint to an API using the Tyk OAS API Designer" >}}
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-no-middleware.png" alt="Tyk OAS API Designer showing no middleware enabled on endpoint" >}}
+
+#### Step 2: Select the Method Transform middleware
+
+Select **ADD MIDDLEWARE** and choose the **Method Transform** middleware from the *Add Middleware* screen.
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-method-transform.png" alt="Adding the Request Method Transform middleware" >}}
+
+#### Step 3: Configure the middleware
+
+Select the new HTTP method to which requests to this endpoint should be transformed
+
+{{< img src="/img/dashboard/api-designer/tyk-oas-method-transform-config.png" alt="Selecting the new HTTP method for requests to the endpoint" >}}
+
+Select **ADD MIDDLEWARE** to apply the change to the middleware configuration.
+
+#### Step 4: Save the API
+
+Select **SAVE API** to apply the changes to your API.
diff --git a/tyk-docs/content/transform-traffic/request-headers.md b/tyk-docs/content/transform-traffic/request-headers.md
index f2f451131e..f7bcddc48a 100755
--- a/tyk-docs/content/transform-traffic/request-headers.md
+++ b/tyk-docs/content/transform-traffic/request-headers.md
@@ -1,170 +1,68 @@
---
date: 2017-03-23T17:46:28Z
-title: Request Headers
-menu:
- main:
- parent: "Transform Traffic"
-weight: 1
+title: Request Header Transformation
+tags: ["Request Transform", "Header Transform", "transform"]
aliases:
- /advanced-configuration/transform-traffic/request-headers/
+description: "How to transform the headers for an API Request"
---
-## Transform Request Headers with the API Definition
+Tyk allows you to modify the headers of incoming requests to your API endpoints before they are passed to your upstream service.
-Tyk enables you to modify header information before it leaves the proxy and is passed to your upstream API or when a response is proxied back to the client. This can be very useful in cases where you have an upstream API that has a single authentication key, and you want to add multi-user access to it without modifying it or adding clunky authentication methods to it to support new users.
+There are two options for this:
+- API-level modification that is applied to all requests to the API
+- endpoint-level modification that is applied only to requests to a specific endpoint
-### Example Scenario
+With the header transform middleware you can append or delete any number of headers to ensure that the request contains the information required by your upstream service. You can enrich the request by adding contextual data that is held by Tyk but not included in the original request from the client.
-You have an API called WidgetsAPI, that takes an x-widgets-secret header to allow access, this is an internal API used by your teams but you want to expose it to your customers and charge them for access.
+This middleware changes only the headers and not the method or payload. You can, however, combine this with the [Request Method Transform]({{< ref "advanced-configuration/transform-traffic/request-method-transform" >}}) and [Request Body Tranform]({{< ref "transform-traffic/request-body" >}}) to apply more complex transformation to requests.
-You could either modify the API and add a whole user, key and access management system, or you could use Tyk to inject this header for you.
+There are related [Response Header Transform]({{< ref "advanced-configuration/transform-traffic/response-headers" >}}) middleware (at API-level and endpoint-level) that provide the same functionality on the response from your upstream, prior to it being returned to the client.
-### Update the API Definition Object
+## When to use request header transformation
-Using Tyk, you would set up your API Definition with these additions to the `extended_paths.transform_headers` field:
+#### Adding Custom Headers
-```{.copyWrapper}
-"extended_paths": {
- "ignored": [],
- "white_list": [],
- "black_list": [],
- "cache": ["get"],
- "transform": [],
- "transform_headers": [
- {
- "delete_headers": ["authorization"],
- "add_headers": {"x-widgets-secret": "the-secret-widget-key-is-secret"},
- "path": "widgets{rest}",
- "method": "GET"
- }
- ]
-}
-```
+A common use of this feature is to add custom headers to requests, such as adding a secure header to all upstream requests (to verify that traffic is coming from the gateway), or adding a timestamp for tracking purposes.
-Now Tyk keys that you create with an Access Definition rule that is set to this API and version, can have quotas, throttling and access checks applied without needing to add any new code or functionality to your existing API.
+#### Modifying Headers for Compatibility
-## Transform Request Headers with the Dashboard
+You could use the request header transform middleware to modify headers for compatibility with a downstream system, such as changing the Content-Type header from "application/json" to "application/xml" for an API that only accepts XML requests while using the [Request Body Tranform]({{< ref "transform-traffic/request-body" >}}) to transform the payload.
-To inject new headers into a request using the GUI, you must make the edits in the Endpoint Designer section of your API Definition.
+#### Prefixing or Suffixing Headers
-### Step 1: Add an Endpoint and select the Modify Headers Plugin
+Upstream systems or corporate policies might mandate that a prefix or suffix is added to header names, such as adding a "Bearer" prefix to all Authorization headers for easier identification internally, without modifying the externally published API consumed by the client applications.
-You must also set a method and a request pattern to match against. These patterns can contain wildcards in the form of any string bracketed by curly braces. These wildcards are so they are human readable and do not translate to variable names. Under the hood, a wildcard translates to the "match everything" regex of: `(.*)`.
+#### Adding multi-user access to a service
-{{< img src="/img/2.10/modify_headers.png" alt="Endpoint designer" >}}
+You can add multi-user access to an upstream API that has a single authentication key and you want to add multi-user access to it without modifying it or adding clunky authentication methods to it to support new users.
-#### Step 2: Select the "Request" tab
+## How the request header transform works
-This ensures that this will only be applied to inbound requests.
+The request header transform can be applied per-API or per-endpoint; each has a separate entry in the API definition so that you can configure both API-level and endpoint-level transforms for a single API.
-{{< img src="/img/2.10/modify_headers1.png" alt="Request tab" >}}
+The middleware is configured with a list of headers to delete from the request and a list of headers to add to the request. Each header to be added to the request is configured as a key:value pair.
-#### Step 3: Setup header modify
+The "delete header" functionality is intended to ensure that any header in the delete list is not present once the middleware completes - so if a header is not originally present in the request but is on the list to be deleted, the middleware will ignore its omission.
-Select set the headers to delete and insert using the provided fields.
-Please note that any header you add would be capitalised. I.e. if you add `x-request-id` in the UI or in the API definition, in the response the caller will get `X-Request-Id`.
+The "add header" functionality will capitalise any header name provided, for example if you configure the middleware to append `x-request-id` it will be added to the request as `X-Request-Id`.
-> **Important**: Remember to click **ADD** to ensure they are added to the list.
+In the request middleware chain, the API-level transform is applied before the endpoint-level transform so if both middleware are enabled, the endpoint-level transform will operate on the headers that have been added by the API-level transform (and will not receive those that have been deleted by it).
-{{< img src="/img/2.10/modify_headers2.png" alt="Header transforms" >}}
+#### Injecting dynamic data into headers
-#### Step 4: Save the API
+You can enrich the request headers by injecting data from context variables or session objects into the headers.
+- [Context variables]({{< ref "context-variables" >}}) are extracted from the request at the start of the middleware chain and can be injected into added headers using the `$tyk_context.` namespace
+- [Session metadata]({{< ref "getting-started/key-concepts/session-meta-data" >}}), from the Tyk Session Object linked to the request, can be injected into added headers using the `$tyk_meta.` namespace
-Once the API is saved, if a request path and method matches your pattern, then the relevant modifications will be made to the request that hits your endpoint.
+
-
+If you're using Tyk OAS APIs, then you can find details and examples of how to configure the request header transform middleware [here]({{< ref "product-stack/tyk-gateway/middleware/request-header-tyk-oas" >}}).
-## Modifying Request Headers Globally
+If you're using Tyk Classic APIs, then you can find details and examples of how to configure the request header transform middleware [here]({{< ref "product-stack/tyk-gateway/middleware/request-header-tyk-classic" >}}).
-### Injecting and Removing Headers Globally
-
-In some cases you may wish to add a secure header to all outbound requests (e.g. to verify that traffic is coming from the gateway), to do so, add this to your version block in your API Definition:
-
-```{.copyWrapper}
-"version_data": {
- "versions": {
- "Default": {
- ...
- "global_headers": {
- "X-Static": "foo",
- "X-Request-ID":"$tyk_context.request_id",
- "X-Path": "$tyk_context.path",
- "X-Remote-Addr": "$tyk_context.remote_addr"
- },
- "global_headers_remove": [
- "auth_id"
- ]
- ...
- }
- }
-},
-```
-
-Using the `global_headers_remove` field it is possible to remove headers from all inbound requests before they are passed to your service.
-
-### Adding Global Injections via the Dashboard
-
-You can also achieve this with the Dashboard, via your API Endpoint Designer, by selecting the **Global Version Settings**:
-
-{{< img src="/img/2.10/global_settings_modify_headers.png" alt="GLobal version settings" >}}
-
-## Injecting Custom Dynamic Data into Headers
-
-It is possible to inject information that is carried within the user session object into the header space as well. Each token or key has an attached session object which contains a `meta_data` field, this is a key/value map that allows for dynamic middleware and other components to intelligently act on identity information from the inbound request without exposing it.
-
-To use this data in your header transform simply access the special `$tyk_meta` namespace, here is a working example.
-
-Say in your session object you have included the following metadata:
-
-```
-"meta_data": {
- "uid": 12345,
- "username": "norman_bates"
-}
-```
-
-To use this in your header transform, your API definition path would be:
-
-```{.copyWrapper}
-"transform_headers": [
- {
- "delete_headers": [],
- "add_headers": {"user-id": "$tyk_meta.uid", "user-name": "$tyk_meta.username"},
- "path": "widgets/{id}",
- "method": "GET"
- },
-]
-```
-
-### Meta Data in the Dashboard
-
-The variable names (`$tyk_meta`) are also available in the Dashboard fields and will work the same way.
-
-### Injecting Context Variables into Headers
-
-As of version 2.2 Tyk allows context variables to be injected into headers using the `$tyk_context.` namespace. See [Context Variables]({{< ref "context-variables" >}}) for more information.
-
-### Example `global_headers` section
-```{.copyWrapper}
-"version_data": {
- "not_versioned": true,
- "versions": {
- "v1": {
- "name": "v1",
- "expires": "2100-01-02 15:04",
- "use_extended_paths": true,
- "paths": {
- "ignored": [],
- "white_list": [],
- "black_list": []
- },
- "global_headers":{
- "X-Static": "foo",
- "X-Request-ID":"$tyk_context.request_id",
- "X-Path": "$tyk_context.path",
- "X-Remote-Addr": "$tyk_context.remote_addr"
- }
- }
- }
-}
-```
\ No newline at end of file
+
diff --git a/tyk-docs/data/menu.yaml b/tyk-docs/data/menu.yaml
index f9aa699843..382c496330 100644
--- a/tyk-docs/data/menu.yaml
+++ b/tyk-docs/data/menu.yaml
@@ -524,13 +524,37 @@ menu:
category: Page
show: True
- title: "Circuit Breakers"
- path: /planning-for-production/ensure-high-availability/circuit-breakers
- category: Page
+ category: Directory
show: True
+ menu:
+ - title: "Overview"
+ path: /planning-for-production/ensure-high-availability/circuit-breakers
+ category: Page
+ show: True
+ - title: "Tyk OAS configuration"
+ path: /product-stack/tyk-gateway/middleware/circuit-breaker-tyk-oas
+ category: Page
+ show: True
+ - title: "Tyk Classic configuration"
+ path: /product-stack/tyk-gateway/middleware/circuit-breaker-tyk-classic
+ category: Page
+ show: True
- title: "Enforced Timeouts"
- path: /planning-for-production/ensure-high-availability/enforced-timeouts
- category: Page
+ category: Directory
show: True
+ menu:
+ - title: "Overview"
+ path: /planning-for-production/ensure-high-availability/enforced-timeouts
+ category: Page
+ show: True
+ - title: "Tyk OAS configuration"
+ path: /product-stack/tyk-gateway/middleware/enforced-timeout-tyk-oas
+ category: Page
+ show: True
+ - title: "Tyk Classic configuration"
+ path: /product-stack/tyk-gateway/middleware/enforced-timeout-tyk-classic
+ category: Page
+ show: True
- title: "Liveness health check"
path: /planning-for-production/ensure-high-availability/health-check
category: Page
@@ -1603,18 +1627,42 @@ menu:
path: /product-stack/tyk-gateway/middleware/internal-endpoint-tyk-classic
category: Page
show: True
- - title: "Request Method Transform"
- path: /advanced-configuration/transform-traffic/request-method-transform
- category: Page
+ - title: "Request Method"
+ category: Directory
show: True
+ menu:
+ - title: "Overview"
+ path: /advanced-configuration/transform-traffic/request-method-transform
+ category: Page
+ show: True
+ - title: "Tyk OAS configuration"
+ path: /product-stack/tyk-gateway/middleware/request-method-tyk-oas
+ category: Page
+ show: True Me
+ - title: "Tyk Classic configuration"
+ path: /product-stack/tyk-gateway/middleware/request-method-tyk-classic
+ category: Page
+ show: True
- title: "Request Body"
path: /transform-traffic/request-body
category: Page
show: True
- title: "Request Headers"
- path: /transform-traffic/request-headers
- category: Page
+ category: Directory
show: True
+ menu:
+ - title: "Overview"
+ path: /transform-traffic/request-headers
+ category: Page
+ show: True
+ - title: "Tyk OAS configuration"
+ path: /product-stack/tyk-gateway/middleware/request-header-tyk-oas
+ category: Page
+ show: True
+ - title: "Tyk Classic configuration"
+ path: /product-stack/tyk-gateway/middleware/request-header-tyk-classic
+ category: Page
+ show: True
- title: "Response Body"
path: /advanced-configuration/transform-traffic/response-body
category: Page