Merge branch 'master' into Improved-virtual-endpoint-and-javascript

tyk-docs/content/advanced-configuration/transform-traffic/endpoint-designer.md

@@ -91,30 +91,7 @@ This plugin allows you to change the method of a request. See [Method Transforms
 
 ### Mock Response
 
-This plugin allows you to mock responses for an API endpoint. This can be useful when creating a new API, or when making a development API available to an external team.
-
-Mocked endpoints will not be authenticated, will not process other middleware configured in the API and will have no analytics.
-
-{{< note success >}}
-**Note**  
-
-For mocks to be enabled, the path must also be in a list. We recommend adding the path to a {{<fn>}}allowlist{{</fn>}}. If this isn't done, then the mock will not be saved on an update.
-{{< /note >}}
-
-
-**API Blueprint**: If you have imported an API Blueprint definition, and selected the mocks option in the importer, then your whole API will be a white list.
-
-{{< note success >}}
-**Note**  
-
-Support for API Blueprint is being deprecated. See [Importing APIs]({{< ref "getting-started/import-apis#api-blueprint-is-being-deprecated" >}}) for more details.
-{{< /note >}}
-
-The options for a mock are:
-
-- **Code**: the status code to respond with
-- **Response body**: The response body
-- **Headers**: The headers to inject with the response
+This plugin allows you to configure Tyk Gateway to respond to requests made to an API endpoint, providing a realistic "mocked" response without making a call to the upstream service. This can be useful when creating a new API, or when making a development API available to an external team. See [Mock Response]({{< ref "product-stack/tyk-gateway/middleware/mock-response-middleware" >}}) for more details.
 
 ### Modify Headers
 
@@ -136,7 +113,7 @@ This plugin allows you to translate an outbound API interface to the internal st
 
 This plugin allows you to verify user requests against a specified JSON schema and check that the data sent to your API by a consumer is in the right format. This means you can offload data validation from your application onto us.
 
-If it's not in the right format, then the request will be rejected. And you can set a custom error code. The default is "422 Unprocessable Entity". See [Validate JSON]({{< ref "advanced-configuration/transform-traffic/validate-json" >}}) for more details.
+If it's not in the right format, then the request will be rejected. And you can set a custom error code. The default is "422 Unprocessable Entity". See [Validate JSON]({{< ref "product-stack/tyk-gateway/middleware/validate-request-tyk-classic" >}}) for more details.
 
 ### Virtual Endpoint
 

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/apim-best-practice/api-security-best-practice/authorisation.md

@@ -23,7 +23,7 @@ Handle with the API. It can access and understand the data needed to make author
 
 Handle with both the API and the gateway. The approach depends on the type of API:
 
-For REST APIs, it’s the API that’s primarily responsible for returning the correct data. To complement this, the gateway can use [body transforms]({{< ref "advanced-configuration/transform-traffic/response-body" >}}) to remove sensitive data from responses if the API is unable to do so itself. The gateway can also enforce object property-level restrictions using [JSON validation]({{< ref "advanced-configuration/transform-traffic/validate-json" >}}), for scenarios where the client is sending data to the API.
+For REST APIs, it’s the API that’s primarily responsible for returning the correct data. To complement this, the gateway can use [body transforms]({{< ref "advanced-configuration/transform-traffic/response-body" >}}) to remove sensitive data from responses if the API is unable to do so itself. The gateway can also enforce object property-level restrictions using [JSON validation]({{< ref "product-stack/tyk-gateway/middleware/validate-request-tyk-classic" >}}), for scenarios where the client is sending data to the API.
 
 For GraphQL APIs, use the gateway to define [GraphQL schemas]({{< ref "graphql-proxy-only#managing-gql-schema" >}}) to limit which properties are queryable, then optionally use [field-based permissions]({{< ref "graphql-proxy-only#field-based-permission" >}}) to also specify access rights to those properties. 
 

tyk-docs/content/basic-config-and-security/control-limit-traffic/request-size-limits.md

@@ -1,83 +1,72 @@
 ---
 date: 2017-03-23T17:18:54Z
 title: Request Size Limits
-tags: ["Request size limits"]
 description: "The key concepts for implementing request size limits with Tyk"
-menu:
-  main:
-    parent: "Control & Limit Traffic"
-weight: 4 
+tags: ["request size limit", "size limit", "security", "middleware", "per-API", "per-endpoint"]
+
 ---
 
-## Overview
+With Tyk, you can apply limits to the size of requests made to your HTTP APIs. You might use this feature to protect your Tyk Gateway or upstream services from excessive memory usage or brute force attacks.
 
-With Tyk, you can apply limits to the size of requests made to your HTTP APIs. You might use this feature to protect your Tyk Gateway or upstream services from avoid excessive memory usage or brute force attacks.
+Tyk Gateway offers a flexible tiered system of limiting request sizes ranging from globally applied limits across all APIs deployed on the gateway down to specific size limits for individual API endpoints.
 
-Tyk offers a flexible tiered system of limiting request sizes ranging from globally applied limits across all APIs deployed on the gateway down to specific size limits for individual API endpoints.
+## When to use the Request Size Limit middleware
 
-All size limits are stated in bytes and are applied only to the request _body_, excluding the headers.
+#### Protecting the entire Tyk Gateway from DDoS attacks
+You can configure a system-wide request size limit that protects all APIs managed by the Tyk Gateway from being overwhelmed by excessively large requests, which could be part of a DDoS attack, ensuring the stability and availability of the gateway.
 
-Tyk compares each incoming API request with the configured maximum size(s) and will reject any request that exceeds the size you have set, returning an HTTP 4xx error as detailed below.
+#### Limiting request sizes for a lightweight microservice
+You might expose an API for a microservice that is designed to handle lightweight, fast transactions and is not equipped to process large payloads. You can set an API-level size limit that ensures the microservice behind this API is not forced to handle requests larger than it is designed for, maintaining its performance and efficiency.
 
-{{< note success >}}
-**Note**  
+#### Controlling the size of GraphQL queries
+A GraphQL API endpoint might be susceptible to complex queries that can lead to performance issues. By setting a request size limit for the GraphQL endpoint, you ensure that overly complex queries are blocked, protecting the backend services from potential abuse and ensuring a smooth operation.
 
-Tyk Cloud Classic enforces a strict request size limit of 1MB on all inbound requests via our cloud architecture. This does not affect Multi-Cloud users.
-{{< /note >}}
+#### Restricting upload size on a file upload endpoint
+An API endpoint is designed to accept file uploads, but to prevent abuse, you want to limit the size of uploads to 1MB. To enforce this, you can enable the Request Size Limit middleware for this endpoint, configuring a size limit of 1MB. This prevents users from uploading excessively large files, protecting your storage and bandwidth resources.
 
-### Applying a size limit for all APIs on your Gateway
-You can optionally configure a request size limit (in bytes) that will be applied to all APIs on your Tyk Gateway by adding `max_request_body_size` to the `http_server_options` [element]({{< ref "/tyk-oss-gateway/configuration#http_server_options" >}}) of your `tyk.conf` Gateway configuration. For example:
-```
-"max_request_body_size": 5000
-```
-
-This Gateway-wide size limit will be evaluated before per-API or per-endpoint settings. If this test fails, the Tyk Gateway will report `413 Request Entity Too Large`.
-
-### Applying a size limit for a specific API
-You can optionally configure a request size limit (in bytes) to an API by adding `global_size_limit` to the `version` element of the API Definition, for example:
-```
-"global_size_limit": 2500 
-```
+## How request size limiting works
 
-This limit is applied for all endpoints _within an API_. It is evaluated after the Gateway-wide size limit and before any endpoint-specific size limit. If this test fails, the Tyk Gateway will report `400 Request is too large`.
+Tyk compares each incoming API request with the configured maximum size for each level of granularity in order of precedence and will reject any request that exceeds the size you have set at any level of granularity, returning an HTTP 4xx error as detailed below.
 
-### Applying a size limit for a specific API endpoint
-Tyk provides a _Request Size Limit_ middleware that can be configured per API endpoint. This gives you the most granular control over request sizes.
+All size limits are stated in bytes and are applied only to the request _body_ (or payload), excluding the headers.
 
-You can configure this easily from the API Designer in the Tyk Dashboard, or by manually adding the configuration to your API definition.
+| Precedence | Granularity      | Error returned on failure      |
+|------------|------------------|--------------------------------|
+| 1st        | System (gateway) | `413 Request Entity Too Large` |
+| 2nd        | API              | `400 Request is too large`     |
+| 3rd        | Endpoint         | `400 Request is too large`     |
 
-This limit will be applied after any Gateway-level or API-level size limits; in keeping with the other size limit options provided by Tyk, this value is given in bytes. If this test fails, the Tyk Gateway will report `400 Request is too large`.
-
-#### Using the Tyk Dashboard
-You can enforce a request size limit for a specific API endpoint using the API Endpoint Designer:
-
-1.  Click **ADD ENDPOINT**.
+{{< note success >}}
+**Note**
 
-2.  Fill in the endpoint pattern with the details of the request (e.g. `GET widgets/{wildcard}`).
+The system level request size limit is the only size limit applied to [TCP]({{< ref "key-concepts/tcp-proxy" >}}) and [Websocket]({{< ref "advanced-configuration/websockets" >}}) connections.
+{{< /note >}}
 
-3.  Select **Request Size Limit** from the "Plugins" drop down.
-
-    {{< img src="/img/2.10/request_size_limit.png" alt="Plugins drop down" >}}
+<hr>
 
-4.  Set the size limit in bytes.
-
-    {{< img src="/img/2.10/request_size_settings.png" alt="Size limit form" >}}
+### Applying a system level size limit
+You can configure a request size limit (in bytes) that will be applied to all APIs on your Tyk Gateway by adding `max_request_body_size` to the `http_server_options` [element]({{< ref "tyk-oss-gateway/configuration#http_server_optionsmax_request_body_size" >}}) of your `tyk.conf` Gateway configuration. For example:
+```yaml
+"max_request_body_size": 5000
+```
+A value of zero (default) means that no maximum is set and the system-wide size limit check will not be performed.
 
-5.  Save the API.
+This limit will be evaluated before API-level or endpoint-level configurations. If this test fails, the Tyk Gateway will return an error `HTTP 413 Request Entity Too Large`.
 
-#### Manually configuring the API Definition
-To add the _Request Size Limit_ middleware to your API Definition, create a new section in the `extended_paths` block of your API Definition configuration called `size_limits`:
+{{< note success >}}
+**Note**  
 
-```{.copyWrapper}
-"size_limits": [
-  {
-    "path": "widget/{id}",
-    "method": "PUT",
-    "size_limit": 1000
-  }
-  ]
-```
+Tyk Cloud Classic enforces a strict request size limit of 1MB on all inbound requests via our cloud architecture. This limit does not apply to Tyk Cloud users.
+{{< /note >}}
 
+<hr>
 
+If you're using Tyk OAS APIs, then you can find details and examples of how to configure an API or endpoint-level request size limit [here]({{< ref "product-stack/tyk-gateway/middleware/request-size-limit-tyk-oas" >}}).
 
+If you're using Tyk Classic APIs, then you can find details and examples of how to configure an API or endpoint-level request size limit [here]({{< ref "product-stack/tyk-gateway/middleware/request-size-limit-tyk-classic" >}}).
 
+<!-- proposed "summary box" to be shown graphically on each middleware page
+ ## Request Size Limit middleware summary
+  - The Request Size Limit middleware is an optional stage in Tyk's API Request processing chain, sitting between the [TBC]() and [TBC]() middleware.
+  - The Request Size Limit middleware can be configured at the system level within the Gateway config, or per-API or per-endpoint level within the API Definition and is supported by the API Designer within the Tyk Dashboard. 
+ -->