[DX-993, TT-11639] Updated multiple middleware for OAS (#4012)

* Updated multiple middleware for OAS
---------

Co-authored-by: dcs3spp <[email protected]>
Co-authored-by: andrei-tyk <[email protected]>

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" >}}
+<hr>
 
-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" >}}).
+
+<!-- proposed "summary box" to be shown graphically on each middleware page
+ ## Request Method Transform middleware summary
+  - The Request Method Transform is an optional stage in Tyk's API Request processing chain, sitting between the [TBC]() and [TBC]() middleware.
+  - The Request Method Transform is configured at the per-endpoint level within the API Definition and is supported by the API Designer within the Tyk Dashboard. 
+ -->

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"
-```
+```
+
+## 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`.

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                      | ✅               | ✅            |