diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-cache-config.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-cache-config.png new file mode 100644 index 00000000000..d350cdc1d8d Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-cache-config.png differ diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-cache.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-cache.png new file mode 100644 index 00000000000..14fec9f4dc1 Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-cache.png differ 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 00000000000..c4bee2ebb16 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 00000000000..7b8abd68276 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 00000000000..81afecb3fc0 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 00000000000..3e351e9b5f4 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 00000000000..8fd8927ad3a 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 00000000000..d2e138a1ee5 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-mock-added.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock-added.png new file mode 100644 index 00000000000..8cb97c1c6c3 Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock-added.png differ diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock-auto-edit.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock-auto-edit.png new file mode 100644 index 00000000000..20522b5bec2 Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock-auto-edit.png differ diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock-auto-options.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock-auto-options.png new file mode 100644 index 00000000000..b131613c78c Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock-auto-options.png differ diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock-auto-select.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock-auto-select.png new file mode 100644 index 00000000000..237bb3c73b8 Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock-auto-select.png differ diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock-manual.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock-manual.png new file mode 100644 index 00000000000..037437de34c Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock-manual.png differ diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock.png new file mode 100644 index 00000000000..6cd0a3959a9 Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-mock.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 00000000000..fdea92a5b4c 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 00000000000..c3d327d8840 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 00000000000..02e46c42ce6 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 00000000000..8c8699aaf70 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 00000000000..84ee26ff3bf Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-header.png differ diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-size-limit-config.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-size-limit-config.png new file mode 100644 index 00000000000..44fa035b5ba Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-size-limit-config.png differ diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-size-limit.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-size-limit.png new file mode 100644 index 00000000000..294062d7796 Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-request-size-limit.png differ diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-validate-request-added.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-validate-request-added.png new file mode 100644 index 00000000000..6a7dacc6816 Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-validate-request-added.png differ diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-validate-request-config.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-validate-request-config.png new file mode 100644 index 00000000000..86f9f83326a Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-validate-request-config.png differ diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-validate-request-import.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-validate-request-import.png new file mode 100644 index 00000000000..566a5f4a67c Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-validate-request-import.png differ diff --git a/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-validate-request.png b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-validate-request.png new file mode 100644 index 00000000000..256d0110808 Binary files /dev/null and b/tyk-docs/assets/img/dashboard/api-designer/tyk-oas-validate-request.png differ diff --git a/tyk-docs/assets/img/dashboard/endpoint-designer/advanced-cache.png b/tyk-docs/assets/img/dashboard/endpoint-designer/advanced-cache.png new file mode 100644 index 00000000000..48e26ac7650 Binary files /dev/null and b/tyk-docs/assets/img/dashboard/endpoint-designer/advanced-cache.png differ diff --git a/tyk-docs/assets/img/dashboard/endpoint-designer/mock-response-config.png b/tyk-docs/assets/img/dashboard/endpoint-designer/mock-response-config.png new file mode 100644 index 00000000000..a4a14c0c764 Binary files /dev/null and b/tyk-docs/assets/img/dashboard/endpoint-designer/mock-response-config.png differ diff --git a/tyk-docs/assets/img/dashboard/endpoint-designer/mock-response.png b/tyk-docs/assets/img/dashboard/endpoint-designer/mock-response.png new file mode 100644 index 00000000000..3868e763504 Binary files /dev/null and b/tyk-docs/assets/img/dashboard/endpoint-designer/mock-response.png differ diff --git a/tyk-docs/assets/img/dashboard/endpoint-designer/validate-json-schema.png b/tyk-docs/assets/img/dashboard/endpoint-designer/validate-json-schema.png new file mode 100644 index 00000000000..9ba450c6a36 Binary files /dev/null and b/tyk-docs/assets/img/dashboard/endpoint-designer/validate-json-schema.png differ diff --git a/tyk-docs/content/advanced-configuration/transform-traffic/endpoint-designer.md b/tyk-docs/content/advanced-configuration/transform-traffic/endpoint-designer.md index c9d4bd4f1b7..04cf0eaa9da 100644 --- a/tyk-docs/content/advanced-configuration/transform-traffic/endpoint-designer.md +++ b/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 {{}}allowlist{{}}. 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 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 1d27643fffd..00e304e7032 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/advanced-configuration/transform-traffic/validate-json.md b/tyk-docs/content/advanced-configuration/transform-traffic/validate-json.md deleted file mode 100644 index 008da165719..00000000000 --- a/tyk-docs/content/advanced-configuration/transform-traffic/validate-json.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Validate JSON -menu: - main: - parent: "Transform Traffic" -weight: 7 -aliases: - - /transform-traffic/validate-json/ ---- - -From Tyk Gateway v2.6.0, you can 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". - -## Validate with an API Definition - -JSON schema validation is implemented as the rest of plugins, and its configuration should be added to `extended_paths` in the following format: - -```{.json} -"validate_json": [{ - "method": "POST", - "path": "me", - "schema": {..schema..}, // JSON object - "error_response_code": 422 // 422 default however can override. -}] -``` - -The schema must be a draft v4 JSON Schema spec, see http://json-schema.org/specification-links.html#draft-4 for details. Example schema can look like this: - -```{.json} -{ - "title": "Person", - "type": "object", - "properties": { - "firstName": { - "type": "string" - }, - "lastName": { - "type": "string" - }, - "age": { - "description": "Age in years", - "type": "integer", - "minimum": 0 - } - }, - "required": ["firstName", "lastName"] -} -``` - -## Validate with the Dashboard - -To add the Validate JSON plugin via the Dashboard: - -1. Select your API from your list and select **Edit**. -2. From the **API Designer**, select the **Endpoint Designer** tab -3. Select an existing endpoint or create a new one. -4. From the Plugins drop-down list, select **VALIDATE JSON** -{{< img src="/img/2.10/validate_json.png" alt="validate json plugin" >}} -5. Click the **VALIDATE JSON** Plugin -6. Select an Error code from the drop-down list if you don't want to use the default `422 UNPROCESSABLE ENTITY` -7. Enter your JSON Schema in the JSON Schema editor. - -{{< img src="/img/dashboard/system-management/validate-json-schema.png" alt="Validate JSON Schema" >}} - -{{< note success >}} - -**Note** - -JSON Schema `draft-04` is required. If you don't specify a schema, `draft-04` is used. Using another version will return an `unsupported schema error, unable to validate` error. - -{{< /note >}} diff --git a/tyk-docs/content/apim-best-practice/api-security-best-practice/authorisation.md b/tyk-docs/content/apim-best-practice/api-security-best-practice/authorisation.md index bf1604f0c7f..6119384e24c 100644 --- a/tyk-docs/content/apim-best-practice/api-security-best-practice/authorisation.md +++ b/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. diff --git a/tyk-docs/content/basic-config-and-security/control-limit-traffic/request-size-limits.md b/tyk-docs/content/basic-config-and-security/control-limit-traffic/request-size-limits.md index 7702eac8603..ba808e0e1d2 100755 --- a/tyk-docs/content/basic-config-and-security/control-limit-traffic/request-size-limits.md +++ b/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" >}} +
-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 >}} +
+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" >}}). + diff --git a/tyk-docs/content/basic-config-and-security/reduce-latency/caching/advanced-cache.md b/tyk-docs/content/basic-config-and-security/reduce-latency/caching/advanced-cache.md index 27da1efccf2..f0fdca756d4 100644 --- a/tyk-docs/content/basic-config-and-security/reduce-latency/caching/advanced-cache.md +++ b/tyk-docs/content/basic-config-and-security/reduce-latency/caching/advanced-cache.md @@ -1,199 +1,47 @@ --- -title: "Advanced Caching" +title: "Endpoint Caching" date: 2023-06-08 -tags: ["Caching", "Dynamic Cache", "Configuration", "Cache", "Endpoint", "Advanced"] -description: "" -menu: - main: - parent: "Caching" -weight: 2 +tags: ["Caching", "Cache", "Endpoint Cache", "selective caching", "middleware", "per-endpoint"] +description: "Detail of the Endpoint Caching middleware" --- -On this page we describe how to configure Tyk's API response cache per endpoint within an API. For details on the API level (Global) cache you should refer to the [global-cache]({{< ref "/basic-config-and-security/reduce-latency/caching/global-cache">}}) configuration page. +When you use the API-level cache, Tyk will maintain a cache entry for each combination of request method, request path (endpoint) and API key (if authentication is enabled) for an API. The Endpoint Caching middleware gives you granular control over which paths are cached and allows you to vary cache configuration across API versions. -By default Tyk maintains a cache entry for each combination of request method, request path (endpoint) and API key (if authentication is enabled) for an API. +For details on the API-level cache you should refer to the [API-level cache]({{< ref "basic-config-and-security/reduce-latency/caching/global-cache">}}) configuration page. -You can optionally choose to cache more selectively so that only a subset of endpoints within the API will be cached. +## When to use the Endpoint Caching middleware +#### API with multiple endpoints +When your API has more than one endpoint the upstream data could have different degrees of freshness, for example the data returned by one endpoint might refresh only once every five minutes (and so should be suitably cached) whilst another might give real-time data and so should not be cached. The endpoint cache allows you to optimise the caching of each endpoint to meet your requirements. -## Configuring the endpoint-level cache -Within the [API Definition]({{< ref "tyk-gateway-api/api-definition-objects">}}), the per-endpoint cache controls are grouped within the `extended_paths` section. +#### Request based caching +If you have an API that's providing search capability (for example into a catalogue of products) and want to optimise the performance for the most frequently requested search terms, you could use the endpoint cache's [request-selective](#request-selective-cache-control) capability to cache only a subset of all requests to an endpoint. -There are two elements within `extended_paths` that are used to configure this granular cache: - - `cache`: Used to cache all safe requests to specific endpoints - - `advance_cache_config`: Used for more granular caching and advanced features - -### Caching by endpoint (all safe requests) +## How the endpoint cache works If caching is enabled then, by default, Tyk will create separate cache entries for every endpoint (path) of your API. This may be unnecessary for your particular API, so Tyk provides a facility to cache only specific endpoint(s). -To configure endpoint-selective caching, you must: - - ensure that `enable_cache` is set to `true` - - ensure that `cache_all_safe_requests` is set to `false` - - add a list of the endpoint(s) to be cached in the `cache` list within the `extended_paths` section of the API definition +The endpoint-level cache relies upon the API-level cache being enabled but then allows you to enable the middleware for the specific endpoints that you wish to cache. No other endpoint requests will be cached. + +For each endpoint in your API with endpoint caching middleware enabled, you can configure which response codes should be cached (for example, you might not want to cache error responses) and also the refresh interval - or timeout - for the cache entries. {{< note success >}} -**Note** +**Note** -You must disable `cache_all_safe_requests` in the [basic (API-wide) caching configuration]({{< ref "/basic-config-and-security/reduce-latency/caching#global-cache-safe-requests">}}) for per-endpoint caching to work, otherwise requests to all endpoints within the API will be cached. +It's important to note that the [cache all safe requests]({{< ref "/basic-config-and-security/reduce-latency/caching#global-cache-safe-requests">}}) feature of the API-level cache will overrule the per-endpoint configuration so you must ensure that both are not enabled for the same API. {{< /note >}} -For example, if you want to cache only the `/widget`, `/badger` and `/fish` endpoints of your API, with a 60 second TTL you would set the following in the API definition: - -``` -"cache_options": { - "enable_cache": true, - "cache_timeout": 60, - "cache_all_safe_requests": false -}, -... -"version_data": { - ... - "versions": { - ... - [versionName]:{ - ... - "use_extended_paths": true, - "extended_paths": { - "cache": [ - "widget", - "badger", - "fish" - ] - } - } - } -} -``` - -### Advanced caching by endpoint -For ultimate control over what Tyk caches, you should use the advanced configuration options for the per-endpoint cache. You can separately configure, for each HTTP method for an endpoint: - - an individual TTL (timeout) define - - a list of HTTP response codes that should be cached - - a pattern match to cache only requests containing specific data (this is explained [here](#selective-caching-by-body-value)) - -To use this most granular functionality of Tyk's cache, you must not enable safe request caching at either the API-level (`cache_all_safe_requests`) or endpoint-level (`cache[]`). - -The fields within `advance_cache_config` provide Tyk with the precise details of how you wish to cache calls to that endpoint (combination of HTTP method and path). - - `method` - HTTP method to be cached (typically `GET`) - - `path`: Must match an endpoint/path provided in the `cache` list. - - `timeout`: Given in seconds (if not provided, the timeout configured in `cache_timeout` will be used) - - `cache_response_codes`: HTTP responses codes to be cached (for example `200`) - - `cache_key_regex`: Pattern match for selective caching by body value - -For example, if you want to cache the `/widget`, `/badger` and `/fish` endpoints of your API with different timeouts (TTL) and for different response codes you might set the following in the API definition: - -``` -"cache_options": { - "enable_cache": true, - "cache_all_safe_requests": false -}, -... -"version_data": { - ... - "versions": { - ... - [versionName]:{ - ... - "use_extended_paths": true, - "extended_paths": { - "advance_cache_config": [ - { - "method":"GET" - "path":"widget" - "timeout":30 - "cache_response_codes": [200] - }, - { - "method":"GET" - "path":"badger" - "timeout":20 - "cache_response_codes": [200, 201] - }, - { - "method":"GET" - "path":"fish" - "timeout":60 - "cache_response_codes": [200] - } - ] - } - } - } -} -``` - -#### Selective caching by body value -You can configure Tyk's cache to create a separate cache entry for each response where the request matches a specific combination of method, path and body content. - -Body value caching is configured within the `extended_paths.advance_cache_config` section in your API definition. - -The string you provide in `cache_key_regex` will be compared with the request body and, if there's a match anywhere in the body, the response will be cached. - -For example, to create a cache entry for each response to a `POST` request to your API's `addBooks` endpoint that contains the string `my_match_pattern` in the body of the request, you would set: -``` -"cache_options": { - "enable_cache": true, - "cache_all_safe_requests": false -}, -... -"version_data": { - ... - "versions": { - ... - [versionName]:{ - ... - "use_extended_paths": true, - "extended_paths": { - "advance_cache_config": [ - { - "method":"POST", - "path":"addBooks", - "cache_key_regex": "my_match_pattern", - "timeout": 60 - } - ] - } - } - } -} -``` - -## Configuring endpoint caching in the Dashboard +#### Request-selective cache control +For ultimate control over what Tyk caches, you can optionally configure the endpoint cache middleware to look for specific content in the request body. Tyk will then create a separate cache entry for each response where the request matches the specific combination of method, path and body content. -### Caching all safe requests by endpoint in the Dashboard -In the Tyk Dashboard you can configure caching per endpoint for your APIs by assigning the cache middleware to the desired combinations of endpoint and HTTP method. +You define a regex pattern and, if Tyk finds a match for this anywhere in the request body, the response will be cached. -**Step 1**: configure the API level caching options from the **Advanced Options** tab in the Endpoint Designer - 1. **Enable caching** to enable the cache middleware - 2. **Cache timeout** to configure the timeout (in seconds) for cached requests - **Cache only these status codes** is where you list which HTTP status codes should be cached. Remember to click **Add** after entering a code to add it to the list. - 4. **Cache all safe requests** ensure that this is **not** selected, otherwise the responses from all endpoints for the API will be cached. - -{{< img src="/img/dashboard/endpoint-designer/cache-options.png" alt="Cache Options" >}} - -**Step 2**: go into the Endpoint Designer tab and for the path(s) you want to cache, select the Cache plugin from the drop-down list. - -{{< img src="/img/2.10/cache_plugin.png" alt="Dropdown list showing Cache plugin" >}} - -### Advanced caching by endpoint in the Dashboard -Similarly, you can configure caching per endpoint for your APIs by assigning the advanced_cache middleware to the desired combinations of endpoint and HTTP method. - -**Step 1**: configure the API level caching options from the **Advanced Options** tab in the Endpoint Designer as follows - 1. **Enable caching** to enable the cache middleware - 2. **Cache timeout** to configure the default timeout (in seconds) for any endpoints for which you don't want to configure individual timeouts - 3. **Cache only these status codes** leave this blank - 4. **Cache all safe requests** ensure that this is **not** selected, otherwise the responses from all endpoints for the API will be cached. - -**Step 2**: go into the Endpoint Designer tab and for the path(s) you want to cache, select the Advanced Cache plugin from the drop-down list. - -**Step 3**: Configure the Advanced Cache (timeout and HTTP response codes) for each combination of path and method as required. If you don't need to set a specific timeout for an endpoint you can leave this blank and Tyk will use the cache timeout configured previously. - -{{< img src="/img/dashboard/endpoint-designer/advanced-cache-config.png" alt="Endpoint cache configuration" >}} - -{{< note success >}} -**Note** - -Body value match caching is not currently exposed in the Dashboard UI, so it must be enabled though either the raw API editor or the Dashboard API. -{{< /note >}} +
+If you're using Tyk OAS APIs, then you can find details and examples of how to configure the Endpoint Caching middleware [here]({{< ref "product-stack/tyk-gateway/middleware/endpoint-cache-tyk-oas" >}}). +If you're using Tyk Classic APIs, then you can find details and examples of how to configure the Endpoint Caching middleware [here]({{< ref "product-stack/tyk-gateway/middleware/endpoint-cache-tyk-classic" >}}). + diff --git a/tyk-docs/content/basic-config-and-security/security/owasp-top-ten.md b/tyk-docs/content/basic-config-and-security/security/owasp-top-ten.md index 12a09300d2e..e6c6faf37a8 100644 --- a/tyk-docs/content/basic-config-and-security/security/owasp-top-ten.md +++ b/tyk-docs/content/basic-config-and-security/security/owasp-top-ten.md @@ -35,7 +35,7 @@ REST APIs provide endpoints that return all properties of an object in the repon From a REST API perspespective, it is the responsibility of the API to ensure that the correct data is retrieved. The Gateway can provide additional security measures as follows: - [Body transformation plugins]({{< ref "advanced-configuration/transform-traffic/request-method-transform" >}}) can be used to remove sensitive data from the response if the API is unable to do so itself. -- [JSON Schema validation]({{< ref "advanced-configuration/transform-traffic/validate-json" >}}) to validate that an incoming data payload meets a defined schema. Payloads that do not adhere to the schema are rejected. +- [JSON Schema validation]({{< ref "product-stack/tyk-gateway/middleware/validate-request-tyk-classic" >}}) to validate that an incoming data payload meets a defined schema. Payloads that do not adhere to the schema are rejected. For GraphQL APIs, the gateway can be used to define the GraphQL schemas, limiting which properties of an object are queryable. Furthermore, access can be controlled to specific properties by configuring [field-based permissions]({{< ref "graphql/field-based-permissions" >}}). Subsequently, the visiblity of a schema's properties can be controlled for different consumers of the GraphQL API. @@ -80,7 +80,7 @@ Furthermore, the APIM can validate authentication and authorisation by scope to Server Side Request Forgery (SSRF) is a security vulnerability in web applications where an attacker can manipulate a server to make unauthorized requests to internal or external resources, potentially leading to data leaks or remote code execution. This can allow an attacker to probe or attack other parts of the application's infrastructure, potentially compromising sensitive information and systems. -This is application specific and is largely the responsibility of the API. However, Tyk Gateway can assist with this form of attack through [JSON schema validation]({{< ref "advanced-configuration/transform-traffic/validate-json" >}}) for incoming payloads. For example, a schema could contain a regular expression to reject localhost URLs. These URLs could be used by an attacker to perform port scanning for example. +This is application specific and is largely the responsibility of the API. However, Tyk Gateway can assist with this form of attack through [JSON schema validation]({{< ref "product-stack/tyk-gateway/middleware/validate-request-tyk-classic" >}}) for incoming payloads. For example, a schema could contain a regular expression to reject localhost URLs. These URLs could be used by an attacker to perform port scanning for example. ## 8 - Security Misconfiguration @@ -122,6 +122,6 @@ Attackers may identify and target the third party APIs/services used by an API. It is the responsibility of the API to provide protection against these attacks. However, if the organisation uses the Gateway as a forwarding proxy to third party APIs, then the following features could be used: -- [JSON Schema validation]({{< ref "advanced-configuration/transform-traffic/validate-json" >}}) to validate that an incoming data payload meets a defined schema. Payloads that do not adhere to the schema are rejected. +- [JSON Schema validation]({{< ref "product-stack/tyk-gateway/middleware/validate-request-tyk-classic" >}}) to validate that an incoming data payload meets a defined schema. Payloads that do not adhere to the schema are rejected. - [TLS]({{< ref "basic-config-and-security/security/tls-and-ssl" >}}) to ensure that clients use the right service and encrypt traffic. - [Versioning]({{< ref "getting-started/key-concepts/versioning" >}}) allows newer versions of third party APIs to coexist with the older versions, facilitating deprecation and sunsetting. diff --git a/tyk-docs/content/context-variables.md b/tyk-docs/content/context-variables.md index ad7e1c275a3..daf40f58a0c 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/key-concepts/low-level-concepts.md b/tyk-docs/content/getting-started/key-concepts/low-level-concepts.md index 2bc4c4eed4e..76604c7a10e 100644 --- a/tyk-docs/content/getting-started/key-concepts/low-level-concepts.md +++ b/tyk-docs/content/getting-started/key-concepts/low-level-concepts.md @@ -15,7 +15,7 @@ Tyk and the OpenAPI Specification (OAS) talk about a number of topics in differe - [Servers]({{< ref "getting-started/key-concepts/servers" >}}) - find out how Tyk integrates neatly between your clients and upstream services, automatically configuring where it will proxy requests - [Authentication]({{< ref "getting-started/key-concepts/authentication" >}}) - with Tyk's OpenAPI implementation you have the option of delegating authentication to the upstream service, or handling it on the Tyk Gateway -- [Mock Responses]({{< ref "getting-started/using-oas-definitions/mock-response" >}}) - Tyk can automatically configure mock response middleware using the configuration included in your OAS document; this allows you to test your APIs without connecting to the upstream services -- [Request Validation]({{< ref "getting-started/key-concepts/request-validation" >}}) - Tyk can protect your APIs by automatically validating the request parameters and payload against a schema that defines what it *should* look like +- [Mock Responses]({{< ref "product-stack/tyk-gateway/middleware/mock-response-middleware" >}}) - Tyk can automatically configure mock response middleware using the configuration included in your OAS document; this allows you to test your APIs without connecting to the upstream services +- [Request Validation]({{< ref "product-stack/tyk-gateway/middleware/validate-request-middleware" >}}) - Tyk can protect your APIs by automatically validating the request parameters and payload against a schema that defines what it *should* look like - [Paths]({{< ref "getting-started/key-concepts/paths" >}}) - this is a section within the OAS definition that instructs Tyk which API paths (also referred to as endpoints) should be configured; Tyk uses this information to determine which middleware should be enabled for each - [Versioning]({{< ref "getting-started/key-concepts/oas-versioning" >}}) - API versioning, a crucial API gateway capability, allows you to update and improve your APIs without breaking existing clients or services diff --git a/tyk-docs/content/getting-started/key-concepts/rate-limiting.md b/tyk-docs/content/getting-started/key-concepts/rate-limiting.md index 8d39f89b03d..552a6d9d34f 100644 --- a/tyk-docs/content/getting-started/key-concepts/rate-limiting.md +++ b/tyk-docs/content/getting-started/key-concepts/rate-limiting.md @@ -23,7 +23,6 @@ Tyk offers the following rate limiting algorithms to protect your APIs: 1. Distributed Rate Limiter. Most performant, not 100% accurate. Recommended for most use cases. Implements the [token bucket algorithm](https://en.wikipedia.org/wiki/Token_bucket). 2. Redis Rate Limiter. Less performant, 100% perfect accuracy. Implements the [sliding window log algorithm](https://developer.redis.com/develop/dotnet/aspnetcore/rate-limiting/sliding-window/). -3. Leaky Bucket Rate Limiter. Implements delays on requests so they can be processed at the configured rate. Implements the [leaky bucket algorithm](https://en.wikipedia.org/wiki/Leaky_bucket). ### Distributed Rate Limiter (DRL) @@ -70,14 +69,6 @@ Read more [about DRL Threshold here]({{< ref "/tyk-oss-gateway/configuration.md# The Redis rate limiter provides 100% accuracy, however instead of using the token bucket algorithm it uses the sliding window log algorithm. This means that if there is a user who abuses the rate limit, this user's requests will be limited until they start respecting the rate limit. In other words, requests that return 429 will count towards their rate limit counter. -### Leaky bucket rate limiter - -Leaky bucket rate limiting will add delays to incoming requests to control the outgoing request rate to what is configured. It handles traffic bursts and smooths them out to the configured rate. - -This option can be enabled using the following configuration option [enable_leaky_bucket_rate_limiter]({{< ref "tyk-oss-gateway/configuration.md#enable_leaky_bucket_rate_limiter" >}}). - -Impact: the gateway needs to queue the requests up to the defined limit and that comes with some performance penalties. The responses add latency if the request rate goes beyond the defined limits. - ## Rate limiting levels Tyk has two approaches to rate limiting: diff --git a/tyk-docs/content/getting-started/key-concepts/request-validation.md b/tyk-docs/content/getting-started/key-concepts/request-validation.md deleted file mode 100644 index 4264e2419a5..00000000000 --- a/tyk-docs/content/getting-started/key-concepts/request-validation.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -title: "Request Validation" -date: 2023-02-13 -tags: ["API", "OAS", "OpenAPI Specification", "Request Validation"] -description: "The low level concepts around OpenAPI Specification support in Tyk" -menu: - main: - parent: "OpenAPI Low Level Concepts" -weight: 3 ---- - -### Introduction - -Tyk can protect any Gateway incoming request by validating the request -parameters and payload against a schema provided for that path's request -body in the OAS API Definition. - -The clever part is that in this schema you can reference another schema defined elsewhere in the API Definition; this lets you write complex validations very efficiently since you don’t need to re-define the validation for a particular object every time you wish to refer to it. - -{{< note success >}} -**Note** - -At this time Tyk only supports local references to schema within the same API Definition, but in future we aim to support schemas defined externally (via URL). -{{< /note >}} - -### How it works - -Request Validation works on operations. To enable request validations for -the parameters, you must declare at least one parameter on an Open API -operation: - -```json -"/pet/{petId}": { - "get": { - "summary": "Find pet by ID", - "operationId": "getPetById", - "parameters": [ - { - "name": "petId", - "in": "path", - "description": "ID of pet to return", - "required": true, - "schema": { - "type": "integer", - "format": "int64" - } - } - ], - ... - } -} -``` - -If there is at least one parameter, that parameter will enable validation -of parameters. - -To configure Request Validation, which will check the body of each API request sent to the endpoint, follow these simple steps: - -1. Define a schema for an `application/json` content type in the `requestBody` section of a path. - -```json -{ - ... - "paths":{ - "/pet":{ - "put":{ - ... - "requestBody":{ - "description":"Update an existent pet in the store", - "content":{ - "application/json":{ - "schema":{ - type: string - } - } - } - } - } - } - } - ... -} -``` - -2. Enable `validateRequest` middleware within the `operations` section of the API definition, using the [operationId]({{< ref "getting-started/key-concepts/paths#operation-id" >}}) to identify the specific endpoint for which validation is to be applied. - -```json -{ - ... - "paths":{ - "/pet":{ - "put":{ - ... - operationId: 'petput', - "requestBody":{ - ... - "content":{ - "application/json":{ - "schema":{ - type: string - } - } - } - } - } - } - } - ... - "x-tyk-api-gateway": { - ... - "middleware": { - ... - "operations": { - ... - "petput": { - "validateRequest": { - "enabled": true - } - } - } - } - } -} -``` - -#### Using references to access shared schemas - -You can define the validation schema directly within the `requestBody` of the path's definition, or you can define it in the separate `components.schemas` section and include a relative reference within the `requestBody`. This allows you to re-use a schema across multiple paths. - - -```json -//SCHEMA DEFINED WITHIN PATH DEFINITION -{ - ... - "paths":{ - "/pet":{ - "put":{ - ... - "requestBody":{ - "description":"Update an existing pet in the store", - "content":{ - "application/json":{ - "schema":{ - type: string - } - } - } - } - } - } - } - ... -} - -//SCHEMA DEFINED WITHIN COMPONENTS.SCHEMAS AND ACCESSED USING RELATIVE REFERENCE -{ - ... - "components": { - "schemas": { - "Pet": { - type: string - } - } - }, - "paths":{ - "/pet":{ - "put":{ - ... - "requestBody":{ - "description":"Update an existing pet in the store", - "content":{ - "application/json":{ - "schema":{ - $ref: "#/components/Pet" - } - } - } - } - } - } - } - ... -} -``` - -### Automatically enable request validation - -When importing an OAS API Definition or updating an existing Tyk OAS API -Definition, `validateRequest` middleware can be automatically configured -by Tyk for all the paths that have a schema configured, by passing -`validateRequest=true` as a query parameter for the IMPORT or PATCH request respectively. diff --git a/tyk-docs/content/getting-started/using-oas-definitions/import-an-oas-api.md b/tyk-docs/content/getting-started/using-oas-definitions/import-an-oas-api.md index 3617552bb5b..d7c770415d2 100644 --- a/tyk-docs/content/getting-started/using-oas-definitions/import-an-oas-api.md +++ b/tyk-docs/content/getting-started/using-oas-definitions/import-an-oas-api.md @@ -845,7 +845,7 @@ You’ll see that Tyk has populated the `middleware` section within the `x-tyk-a For more information on how Tyk builds the `middleware.operations` structure to configure middleware, see [Paths]({{< ref "/content/getting-started/key-concepts/paths.md" >}}). -For more information on mock responses, see the dedicated [page]({{< ref "/getting-started/using-oas-definitions/mock-response" >}}). +For more information on mock responses, see the dedicated [page]({{< ref "product-stack/tyk-gateway/middleware/mock-response-middleware" >}}). ```.json { @@ -933,7 +933,7 @@ When importing OpenAPI Documents using the Dashboard, Tyk detects the version of #### Automatic Configuration options -- **Generate Validate Request Middleware**: You can automatically validate paths that have the `requestBody` and `schema` fields configured. This allows your Tyk Gateway to validate your request payload against the schema provided in your definition. See [Request Validation]({{< ref "/content/getting-started/key-concepts/request-validation.md" >}}) for more details. +- **Generate Validate Request Middleware**: You can automatically validate paths that have the `requestBody` and `schema` fields configured. This allows your Tyk Gateway to validate your request payload against the schema provided in your definition. See [Request Validation]({{< ref "product-stack/tyk-gateway/middleware/validate-request-middleware" >}}) for more details. - **Apply Detected Authentication**: You can automatically apply the authentication specified in the `security` and `securitySchemes` sections of your definition. See [Authentication]({{< ref "/content/getting-started/key-concepts/authentication.md" >}}) for more details. - **Allow access only to defined paths**: You can restrict access to the paths documented in your definition. See [Paths]({{< ref "/content/getting-started/key-concepts/paths.md" >}}) for more details. diff --git a/tyk-docs/content/getting-started/using-oas-definitions/mock-response.md b/tyk-docs/content/getting-started/using-oas-definitions/mock-response.md deleted file mode 100644 index b79c4c56c9f..00000000000 --- a/tyk-docs/content/getting-started/using-oas-definitions/mock-response.md +++ /dev/null @@ -1,400 +0,0 @@ ---- -title: "Tyk OAS Mock Response" -date: 2022-10-18 -tags: ["Tyk Tutorials", "Getting Started", "First API", "Tyk Cloud", "Tyk Self-Managed", "Tyk Open Source", "Mock Response with an OAS API"] -description: "Using mock response middleware with Tyk OAS APIs" -menu: - main: - parent: "OpenAPI Low Level Concepts" -weight: 6 ---- - -### Introduction - -The mock response middleware allows you to configure Tyk to return a response for an API endpoint without requiring an upstream service. This can be useful when creating a new API or making a development API available to an external team. - -Tyk Classic APIs can be configured with a basic [mock response middleware]({{< ref "/advanced-configuration/transform-traffic/endpoint-designer#mock-response" >}}). Tyk OAS APIs can be configured with a much more flexible mock response which has extended capabilities that respect authentication and other middleware configured for the endpoint. - -There are two methods by which you can add a mock response to an endpoint: - - manual configuration of the mock response middleware - - automatic configuration from the OAS description of the API - -### Manual configuration of mock response middleware - -The mock response middleware can be added to the `operations` section of your Tyk OAS API Definition. You can configure the HTTP status code, headers and body/payload that will be returned in response to a request to the endpoint. - -For example: - -```.json -"operations": { - "my-operation-id": { - "mockResponse": { - "enabled": true, - "code": 200, - "body": "mock-response-body", - "headers": { - "mock-header-1": "mock-header-value-1", - "mock-header-2": "mock-header-value-2" - } - } - } -} -``` -{{< note success >}} -**Note** - -If `code` is not set, `200` is the default response. -{{< /note >}} - -### Automatic configuration from the OAS description of the API - -This is a second and cool way of defining a mock response for an endpoint. The OpenAPI Specification [documents](https://learn.openapis.org/specification/docs.html#the-example-object) response details for an endpoint according to response code and content type. Each response type may have `example`, `examples` or `schema` defined. These can be used as a mock response with Tyk. To enable it, just set `fromOASExamples` to `true`. - -For example: - -```.json -"operations": { - "my-operation-id": { - "mockResponse": { - "enabled": true, - "fromOASExamples": { - "enabled": true - } - } - } -} -``` -`fromOASExamples` has more fields to select as a mock response; `code`, `contentType`, and `exampleName`. For example: - -```.json -"fromOASExamples": { - "enabled": true, - "code": 200, - "contentType": "application/json", - "exampleName": "first-example" -} -``` -{{< note success >}} -**Note** - -If `code` is not set, `200` is the default response. If `contentType` is not set, `application/json` is the default. -{{< /note >}} - -`exampleName` is only valid where there are examples defined in the response documentation. See below. - -With a request, you can override the configured `code`, `contentType`, and `exampleName`. Here are the special headers for it: - -- `Accept`: Overrides the response content type i.e. `application/json`, `text/plain`. This is a standard HTTP header. -- `X-Tyk-Accept-Example-Code`: Overrides the deafult response code i.e. `400`. -- `X-Tyk-Accept-Example-Name`: Overrides the selected example among multiple examples i.e. `second-example`. - -If an example response can’t be found in the configured code, `contentType` or `exampleName`, an error will be returned with `404`. For example: - -```.bash -curl --request GET --header 'X-Tyk-Accept-Example-Code: 512' - 'http://tyk-gateway:8181/my-api/get' - -{ - "error": "mock: there is no example response for the code: 512" -} -``` -#### Extract response code and body - -A HTTP response has three main parts; `code`, `body`, and `headers`. Here's how to extract code and body from an OAS response definition. - -In an OAS response definition, there is an `example` field showing a possible response when calling this endpoint. Tyk can extract it to use it as a response when `fromOASExamples` is set to `true`. For example: - -```.json -{ - ... - "paths": { - "/get": { - "get": { - "operationId": "getget", - "responses": { - "200": { - "content": { - "application/json": { - "example": "Foo" - } - }, - "description": "" - } - } - } - } - }, - "x-tyk-api-gateway": { - ... - "middleware": { - ... - "operations": { - "getget": { - "mockResponse": { - "enabled": true, - "fromOASExamples": { - "enabled": true - } - } - } - } - } - } -} -``` -#### Sample Request - -```.curl -curl --request GET 'http://tyk-gateway:8181/my-api/get' - -"Foo" -``` -### Examples - -In an OAS response definition, `examples` is used to define multiple examples for the same response. It is mutually exclusive with `example`. Only one can be selected, example or examples. Both can’t be set at the same time. - -Let’s assume that `examples` exist. However, if there are multiple `examples` added, which one does Tyk select and return? That’s where `exampleName` comes in. In the `fromOASExamples`, the default `exampleName` can be selected. Or you can set it via the request header `X-Tyk-Accept-Example-Name`. - -{{< note success >}} -**Note** - -The `example` name set in the request header overrides the configured one. If the request header and the configuration don’t have it, Tyk will select randomly from the multiple `examples`. And, yes, that means the response may change with every request. -{{< /note >}} - -```.json -{ - ... - "paths": { - "/get": { - "get": { - "operationId": "getget", - "responses": { - "200": { - "content": { - "application/json": { - "examples": { - "first-example": { - "value": "Foo" - }, - "second-example": { - "value": "Bar" - } - } - } - }, - "description": "" - } - } - } - } - }, - "x-tyk-api-gateway": { - ... - "middleware": { - ... - "operations": { - "getget": { - "mockResponse": { - "enabled": true, - "fromOASExamples": { - "enabled": true - } - } - } - } - } - } -} -``` -#### Sample Requests - -```.curl -curl --request GET --header 'X-Tyk-Accept-Example-Name: first-example' - 'http://tyk-gateway:8181/my-api/get' - -"Foo" -``` - -```.curl -curl --request GET --header 'X-Tyk-Accept-Example-Name: second-example' - 'http://tyk-gateway:8181/my-api/get' - -"Bar" -``` - -### Schema - -If there is no `example` or `examples` defined, Tyk will try to find a schema for the response. If there is a schema, it will be used to generate a mock response. Each schema field may have an example field and they can be used to build a mock response. - -```.json -{ - ... - "paths": { - "/get": { - "get": { - "operationId": "getget", - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "lastName": { - "example": "Bar", - "type": "string" - }, - "name": { - "example": "Foo", - "type": "string" - } - } - } - } - }, - "description": "" - } - } - } - } - }, - "x-tyk-api-gateway": { - ... - "middleware": { - ... - "operations": { - "getget": { - "mockResponse": { - "enabled": true, - "fromOASExamples": { - "enabled": true - } - } - } - } - } - } -} -``` -#### Sample Request - -```.curl -curl --request GET 'http://tyk-gateway:8181/my-api/get' - -{ - "name": "Foo", - "lastName": "Bar" -} -``` - -The schema properties may not have `example` values. In that situation, the default values are used to build a response. See the following examples for each type: - -- `string` > `string` -- `integer` > `0` -- `boolean` > `true` - -### Using $ref and nested schema - -In the above example, the schema was inline. However, Tyk is smart enough to extract values from a referenced or a nested schema object as well. For example: - -```.json -{ - "components": { - "schemas": { - "Engineer": { - "type": "object", - "properties": { - "lastName": { - "example": "Senharputlu", - "type": "string" - }, - "name": { - "example": "Furkan", - "type": "string" - } - } - } - } - }, - "paths": { - "/get": { - "get": { - "operationId": "getget", - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Engineer" - } - } - } - } - } - } - } - } -} -``` - -### Extract response headers - -In the OAS response definition, `headers` is used to document the returned headers from that endpoint. Tyk can build the mock response headers with them. `headers` don’t have any standalone `example` or `examples` attributes, it just has `schema`. Tyk uses that `schema` as in the response body. For example: - -```.json -{ - ... - "paths": { - "/get": { - "get": { - "operationId": "getget", - "responses": { - "200": { - "headers": { - "X-Mock-Header": { - "schema": { - "type": "string", - "example": "Foo" - } - } - }, - "content": {...}, - "description": "" - } - } - } - } - }, - "x-tyk-api-gateway": { - ... - "middleware": { - ... - "operations": { - "getget": { - "mockResponse": { - "enabled": true, - "fromOASExamples": { - "enabled": true - } - } - } - } - } - } -} -``` -#### Sample Request - -```..curl -curl -I --request GET 'http://tyk-gateway:8181/my-api/get' - -HTTP/1.1 200 OK -Content-Type: application/json -X-Mock-Header: Foo <-------- the extracted mock header -X-Ratelimit-Limit: 0 -X-Ratelimit-Remaining: 0 -X-Ratelimit-Reset: 0 -Date: Fri, 07 Oct 2022 12:11:00 GMT -Content-Length: 42 -Connection: close -``` 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 57edaf38ddf..2006d9cd46c 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 3db999e4690..89e2beb6be3 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 4a58e0fddd6..6b9c714fc77 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-dashboard/release-notes/version-5.0.md b/tyk-docs/content/product-stack/tyk-dashboard/release-notes/version-5.0.md index c057189d336..1bf67925d29 100644 --- a/tyk-docs/content/product-stack/tyk-dashboard/release-notes/version-5.0.md +++ b/tyk-docs/content/product-stack/tyk-dashboard/release-notes/version-5.0.md @@ -132,7 +132,7 @@ Tyk Dashboard has been enhanced with **all the custom middleware options** for T Tyk Dashboard hasn’t been left out, we’ve implemented a brand new version management UI for Tyk OAS APIs, to make it as easy as possible for you to manage those API versions as you develop and extend your API products with Tyk. -We’ve improved support for [OAS Mock Responses]({{< ref "getting-started/using-oas-definitions/mock-response" >}}), with the Tyk OAS API definition now allowing you to register multiple Mock Responses in a single API, providing you with increased testing flexibility. +We’ve improved support for [OAS Mock Responses]({{< ref "product-stack/tyk-gateway/middleware/mock-response-middleware" >}}), with the Tyk OAS API definition now allowing you to register multiple Mock Responses in a single API, providing you with increased testing flexibility. Another new feature in the Tyk OAS API Designer is that you can now update (PATCH) your existing Tyk OAS APIs through the Dashboard API without having to resort to curl. That should make life just that little bit easier. Of course, we’ve also addressed some bugs and usability issues as part of our ongoing ambition to make Tyk OAS API the best way for you to create and manage your APIs. 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 00000000000..e69de29bb2d diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/allow-list-tyk-oas.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/allow-list-tyk-oas.md index 2a2880333be..bcf327935ab 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/allow-list-tyk-oas.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/allow-list-tyk-oas.md @@ -94,8 +94,8 @@ The configuration above is a complete and valid Tyk OAS API Definition that you ## Configuring the allow list in the API Designer Adding the allow list to your API endpoints is easy is easy when using the API Designer in the Tyk Dashboard, simply follow the following steps: -##### Step 1: Add an endpoint for the path and select the Response Header Transform middleware -From the **API Designer** add an endpoint that matches the path for which you want to modify the response. +#### 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" >}} @@ -103,12 +103,12 @@ From the **API Designer** add an endpoint that matches the path for which you wa {{< 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 Allow List middleware Select **ADD MIDDLEWARE** and choose the **Allow List** middleware from the *Add Middleware* screen. {{< img src="/img/dashboard/api-designer/tyk-oas-allow.png" alt="Adding the Allow List middleware" >}} -##### Step 2: Optionally configure case-insensitivity +#### Step 3: Optionally configure case-insensitivity If you want to disable case-sensitivity for the allow list, then you must select **EDIT** on the Allow List icon. {{< img src="/img/dashboard/api-designer/tyk-oas-allow-added.png" alt="Allow List middleware added to endpoint - click through to edit the config" >}} @@ -118,5 +118,5 @@ This takes you to the middleware configuration screen where you can alter the ca Select **UPDATE MIDDLEWARE** to apply the change to the middleware configuration. -##### Step 3: Save the API +#### 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/block-list-tyk-oas.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/block-list-tyk-oas.md index 505fa56096c..145d8aba3ba 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/block-list-tyk-oas.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/block-list-tyk-oas.md @@ -94,8 +94,8 @@ The configuration above is a complete and valid Tyk OAS API Definition that you ## Configuring the block list in the API Designer Adding the block list to your API endpoints is easy is easy when using the API Designer in the Tyk Dashboard, simply follow the following steps: -##### Step 1: Add an endpoint for the path and select the Response Header Transform middleware -From the **API Designer** add an endpoint that matches the path for which you want to modify the response. +#### 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" >}} @@ -103,11 +103,12 @@ From the **API Designer** add an endpoint that matches the path for which you wa {{< 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 Block List middleware Select **ADD MIDDLEWARE** and choose the **Block List** middleware from the *Add Middleware* screen. {{< img src="/img/dashboard/api-designer/tyk-oas-block.png" alt="Adding the Block List middleware" >}} -##### Step 2: Optionally configure case-insensitivity +#### Step 3: Optionally configure case-insensitivity If you want to disable case-sensitivity for the block list, then you must select **EDIT** on the Block List icon. {{< img src="/img/dashboard/api-designer/tyk-oas-block-added.png" alt="Block List middleware added to endpoint - click through to edit the config" >}} @@ -117,5 +118,5 @@ This takes you to the middleware configuration screen where you can alter the ca Select **UPDATE MIDDLEWARE** to apply the change to the middleware configuration. -##### Step 3: Save the API +#### 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/circuit-breaker-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/circuit-breaker-tyk-classic.md new file mode 100644 index 00000000000..a4419dbbfb4 --- /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 00000000000..a3cc6fc3f72 --- /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/endpoint-cache-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/endpoint-cache-tyk-classic.md new file mode 100644 index 00000000000..1e0aad06917 --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/endpoint-cache-tyk-classic.md @@ -0,0 +1,168 @@ +--- +title: Using the Endpoint Caching middleware with Tyk Classic APIs +date: 2024-01-24 +description: "Using the Endpoint Caching middleware with Tyk Classic APIs" +tags: ["Caching", "Cache", "Endpoint Cache", "selective caching", "middleware", "per-endpoint", "Tyk Classic"] +--- + +The [Endpoint Caching]({{< ref "basic-config-and-security/reduce-latency/caching/advanced-cache" >}}) middleware allows you to perform selective caching for specific endpoints rather than for the entire API, giving you granular control over which paths are cached. + +When working with Tyk Classic APIs the middleware 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/endpoint-cache-tyk-oas" >}}) page. + +## Configuring the middleware in the Tyk Classic API Definition +When using the Tyk Classic API Definition, there are two options for endpoint caching - simple and advanced. + +The [simple](#simple-endpoint-cache) option works with the API-level cache and allows you to select which endpoints are cached, but relies upon the cache timeout (refresh) configured at the API-level. It will cache all responses received from the endpoint regardless of the HTTP response code for all [safe requests]({{< ref "basic-config-and-security/reduce-latency/caching#global-cache-safe-requests">}}). + +The [advanced](#advanced-endpoint-cache) option allows you to cache more selectively, giving control over the HTTP response codes to be cached, a per-endpoint cache timeout and also the possibility of caching responses only to requests containing specific data in the request body. + +#### Simple endpoint cache +To enable the simple middleware you must add a new `cache` object to the `extended_paths` section of your API definition. The `cache` object is a list of endpoints for which you wish to cache all safe requests. + +In the API-level `cache_options` you must enable caching and configure the timeout whilst ensuring that the option to cache all safe requests is disabled. + +The `cache_options` object has the following configuration: + - `enable_cache`: set to `true` to enable caching for this API + - `cache_all_safe_requests`: set to `false` to allow selective caching per-endpoint + - `cache_timeout`: set to the refresh period for the cache (in seconds) + +For example: +```.json {linenos=true, linenostart=1} +{ + "cache_options": { + "enable_cache": true, + "cache_timeout": 60, + "cache_all_safe_requests": false + }, + + "extended_paths": { + "cache": [ + { + "/widget", + "/fish" + } + ] + } +} +``` + +In this example the endpoint caching middleware has been configured to cache all safe requests to two endpoints (`/widget` and `/fish`) with a cache refresh period of 60 seconds. + +#### Advanced endpoint cache +For ultimate control over what Tyk caches, you should use the advanced configuration options for the per-endpoint cache. You can separately configure, for each HTTP method for an endpoint: + - an individual cache refresh (timeout) + - a list of HTTP response codes that should be cached + - a pattern match to cache only requests containing specific data in the [request body]({{< ref " basic-config-and-security/reduce-latency/caching/advanced-cache#selective-caching-by-body-value" >}}) + +To enable the advanced middleware you must add a new `advance_cache_config` object to the `extended_paths` section of your API definition. + +In the API-level `cache_options` you must enable caching and ensure that the option to cache all safe requests is disabled. The timeout that you set here will be used as a default for any endpoints for which you don't want to configure individual timeouts. + +The `advance_cache_config` object has the following configuration: + - `path`: the endpoint path + - `method`: the endpoint method + - `timeout`: set to the refresh period for the cache (in seconds) + - `cache_response_codes`: HTTP responses codes to be cached (for example `200`) + - `cache_key_regex`: pattern match for selective caching by body value + +For example: +```.json {linenos=true, linenostart=1} +{ + "cache_options": { + "enable_cache": true, + "cache_timeout": 60, + "cache_all_safe_requests": false + }, + + "extended_paths": { + "advance_cache_config": [ + { + "disabled": false, + "method": "POST", + "path": "/widget", + "cache_key_regex": "", + "cache_response_codes": [ + 200 + ], + "timeout": 10 + }, + { + "disabled": false, + "method": "GET", + "path": "/fish", + "cache_key_regex": "^shark$", + "cache_response_codes": [ + 200, 300 + ], + "timeout": 0 + } + ] + } +} +``` + +In this example the endpoint caching middleware has been configured to cache requests to two endpoints (`/widget` and `/fish`) as follows: + +| endpoint | HTTP response codes to cache | cache refresh timeout | body value regex | +|----------|------------------------------|-----------------------|------------------| +| `POST /widget` | 200 | 10 seconds | none | +| `GET /fish` | 200, 300 | 60 seconds (taken from `cache_options`) | `shark` | + +## Configuring the middleware in the API Designer + +You can use the API Designer in the Tyk Dashboard to configure the endpoint caching middleware for your Tyk Classic API by following these steps. + +### Simple endpoint cache + +To enable and configure the simple endpoint cache, follow these instructions: + +##### Step 1: Configure the API level caching options +From the **Advanced Options** tab configure the cache as follows: + - **Enable caching** to enable the cache middleware + - **Cache timeout** to configure the timeout (in seconds) for cached requests + - **Cache only these status codes** is a list of HTTP status codes that should be cached, remember to click **Add** after entering each code to add it to the list + - **Cache all safe requests** ensure that this is **not** selected, otherwise the responses from all endpoints for the API will be cached + +{{< img src="/img/dashboard/endpoint-designer/cache-options.png" alt="Cache Options" >}} + +##### Step 2: Add an endpoint for the path and select the plugin +From the **Endpoint Designer** add an endpoint that matches the path for which you want to cache responses. Select the **Cache** plugin. + +{{< img src="/img/2.10/cache_plugin.png" alt="Dropdown list showing Cache plugin" >}} + +##### Step 3: Save the API +Use the *save* or *create* buttons to save the changes and activate the middleware. + +### Advanced endpoint cache + +To enable and configure the advanced endpoint cache, follow these instructions: + +##### Step 1: Configure the API level caching options +From the **Advanced Options** tab configure the cache as follows: + - **Enable caching** to enable the cache middleware + - **Cache timeout** to configure the default timeout (in seconds) for any endpoints for which you don't want to configure individual timeouts + - **Cache only these status codes** leave this blank + - **Cache all safe requests** ensure that this is **not** selected, otherwise the responses from all endpoints for the API will be cached + +{{< img src="/img/dashboard/endpoint-designer/cache-options.png" alt="Cache Options" >}} + +##### Step 2: Add an endpoint for the path and select the plugin +From the **Endpoint Designer** add an endpoint that matches the path for which you want to cache responses. Select the **Advanced Cache** plugin. + +{{< img src="/img/dashboard/endpoint-designer/advanced-cache.png" alt="Selecting the Advanced Cache plugin for a Tyk Classic API" >}} + +##### Step 3: Configure the Advanced Cache plugin +Set the timeout and HTTP response codes for the endpoint. If you don't need to set a specific timeout for an endpoint you can leave this blank and Tyk will use the cache timeout configured at the API level. + +{{< img src="/img/dashboard/endpoint-designer/advanced-cache-config.png" alt="Endpoint cache configuration for Tyk Classic API" >}} + +{{< note success >}} +**Note** + +Body value match or [request selective]({{< ref "basic-config-and-security/reduce-latency/caching/advanced-cache#request-selective-cache-control" >}}) caching is not currently exposed in the Dashboard UI, so it must be configured through either the raw API editor or the Dashboard API. +{{< /note >}} + +##### Step 4: Save the API +Use the *save* or *create* buttons to save the changes and activate the middleware. diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/endpoint-cache-tyk-oas.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/endpoint-cache-tyk-oas.md new file mode 100644 index 00000000000..fc37ea06cdc --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/endpoint-cache-tyk-oas.md @@ -0,0 +1,131 @@ +--- +title: Using the Endpoint Caching middleware with Tyk OAS APIs +date: 2024-01-24 +description: "Using the Endpoint Caching middleware with Tyk OAS APIs" +tags: ["Caching", "Cache", "Endpoint Cache", "selective caching", "middleware", "per-endpoint", "Tyk OAS"] +--- + +The [Endpoint Caching]({{< ref "basic-config-and-security/reduce-latency/caching/advanced-cache" >}}) middleware allows you to perform selective caching for specific endpoints rather than for the entire API, giving you granular control over which paths are cached. + +When working with Tyk OAS APIs the middleware 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/endpoint-cache-tyk-classic" >}}) page. + +## Configuring the middleware 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. + +Configuring the endpoint cache is performed in two parts: + +#### 1. Enable Tyk's caching function +The caching function is enabled by adding the `cache` object to the `global` section of the Tyk OAS Extension (`x-tyk-api-gateway`) in your Tyk OAS API. + +This object has the following configuration: + - `enabled`: enable the cache for the API + - `timeout`: set as the default cache refresh period for any endpoints for which you don't want to configure individual timeouts (in seconds) + +#### 2. Enable and configure the middleware for the specific endpoint +The endpoint caching middleware (`cache`) should then be added to the `operations` section of `x-tyk-api-gateway` for the appropriate `operationId` (as configured in the `paths` section of your OpenAPI Document). + +The `cache` object has the following configuration: + - `enabled`: enable the middleware for the endpoint + - `timeout`: set to the refresh period for the cache (in seconds) + - `cacheResponseCodes`: HTTP responses codes to be cached (for example `200`) + - `cacheByRegex`: Pattern match for [selective caching by body value]({{< ref "basic-config-and-security/reduce-latency/caching/advanced-cache#selective-caching-by-body-value" >}}) + +For example: +```.json {hl_lines=["37-40", "45-51"],linenos=true, linenostart=1} +{ + "components": {}, + "info": { + "title": "example-endpoint-cache", + "version": "1.0.0" + }, + "openapi": "3.0.3", + "paths": { + "/delay/5": { + "post": { + "operationId": "delay/5post", + "responses": { + "200": { + "description": "" + } + } + } + } + }, + "x-tyk-api-gateway": { + "info": { + "name": "example-endpoint-cache", + "state": { + "active": true + } + }, + "upstream": { + "url": "http://httpbin.org/" + }, + "server": { + "listenPath": { + "value": "/example-endpoint-cache/", + "strip": true + } + }, + "global": { + "cache": { + "enabled": true, + "timeout": 60 + } + }, + "middleware": { + "operations": { + "delay/5post": { + "cache": { + "enabled": true, + "cacheResponseCodes": [ + 200 + ], + "timeout": 5 + } + } + } + } + } +} +``` + +In this example the endpoint cache middleware has been configured to cache `HTTP 200` responses to requests to the `POST /delay/5` endpoint. The cache will refresh after 5 seconds. Note that requests to other endpoints will also be cached, with a default cache timeout of 60 seconds according to the configuration in lines 37-40. + +The configuration above is a complete and valid Tyk OAS API Definition that you can import into Tyk to try out the endpoint caching. + +## Configuring the middleware in the API Designer +Adding endpoint caching to your API endpoints is easy when using the API Designer in the Tyk Dashboard, simply follow the following steps: + +##### Step 1: Add an endpoint +From the **API Designer** add an endpoint 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 Endpoint Cache middleware +Select **ADD MIDDLEWARE** and choose the **Cache** middleware from the *Add Middleware* screen. + +{{< img src="/img/dashboard/api-designer/tyk-oas-cache.png" alt="Adding the Endpoint Cache middleware" >}} + +##### Step 3: Configure the middleware +Set the timeout and HTTP response codes for the endpoint. You can remove a response code from the list by clicking on the `x` next to it. + +{{< img src="/img/dashboard/api-designer/tyk-oas-cache-config.png" alt="Configuring the endpoint cache middleware for a Tyk OAS API" >}} + +{{< note success >}} +**Note** + +Body value match or [request selective]({{< ref "basic-config-and-security/reduce-latency/caching/advanced-cache#request-selective-cache-control" >}}) caching is not currently exposed in the Dashboard UI, so it must be enabled though either the raw API editor or the Dashboard API. +{{< /note >}} + +Select **UPDATE 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 00000000000..39d402e554b --- /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 00000000000..094336f8f00 --- /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/ignore-tyk-oas.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/ignore-tyk-oas.md index 99e7255bc63..55596aaa53b 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/ignore-tyk-oas.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/ignore-tyk-oas.md @@ -106,8 +106,8 @@ The configuration above is a complete and valid Tyk OAS API Definition that you Adding and configuring the Ignore Authentication middleware to your API endpoints is easy when using the API Designer in the Tyk Dashboard, simply follow the following steps: -#### Step 1: Add an endpoint for the path -From the **API Designer** add an endpoint that matches the path you want to rewrite. +#### 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" >}} @@ -132,4 +132,3 @@ Select **UPDATE MIDDLEWARE** to apply the change to the middleware configuration ##### Step 4: Save the API Select **SAVE API** to apply the changes to your API. - \ No newline at end of file diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/internal-endpoint-tyk-oas.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/internal-endpoint-tyk-oas.md index d1dc2a30652..e500e3c4ed3 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/internal-endpoint-tyk-oas.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/internal-endpoint-tyk-oas.md @@ -101,8 +101,8 @@ The configuration above is a complete and valid Tyk OAS API Definition that you Adding the Internal Endpoint middleware to your API endpoints is easy when using the API Designer in the Tyk Dashboard, simply follow the following steps: -#### Step 1: Add an endpoint for the path -From the **API Designer** add an endpoint that matches the path you want to rewrite. +#### 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" >}} @@ -116,4 +116,4 @@ Select **ADD MIDDLEWARE** and choose the **Internal** middleware from the *Add M {{< img src="/img/dashboard/api-designer/tyk-oas-internal.png" alt="Adding the Internal Endpoint middleware" >}} #### Step 3: Save the API -Select **SAVE API** to apply the changes to your API. \ No newline at end of file +Select **SAVE API** to apply the changes to your API. diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-middleware.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-middleware.md new file mode 100644 index 00000000000..09adb8cd8d7 --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-middleware.md @@ -0,0 +1,56 @@ +--- +title: "Mock Response middleware" +date: 2024-01-31 +description: "Explains the Mock Response middleware" +tags: ["mock response", "mock", "middleware", "per-endpoint"] +aliases: + - /getting-started/using-oas-definitions/mock-response/ +--- + +A mock response is a simulated API response that can be returned by the API gateway without actually sending the request to the backend API. Mock responses are an integral feature for API development, enabling developers to emulate API behaviour without the need for upstream execution. + +Tyk's mock response middleware offers this functionality by allowing the configuration of custom responses for designated endpoints. This capability is crucial for facilitating front-end development, conducting thorough testing, and managing unexpected scenarios or failures. + +## When to use the Mock Response middleware + +#### Rapid API Prototyping +Developers can create mock responses during early API prototyping phases to simulate responses while the actual API is still under construction. This allows front-end developers, product managers, and others to validate concepts without blocking on full API implementations upfront. + +#### Legacy System Migration +When migrating from a legacy system to new APIs, mock responses can be used to emulate the old system's outputs during the transitional phases. This provides continuity for client apps relying on the old system while new APIs are built that will eventually replace the legacy hooks. + +#### Disaster Recovery Testing +The ability for a gateway to return well-formed mocks when backend APIs are unavailable helps test disaster recovery plans. By intentionally taking APIs offline and verifying the mocks' surface instead, developers gain confidence in the gateway's fallback and business continuity capabilities + +#### Enhanced CI/CD pipeline +Test cases that rely on API interactions can mock those dependencies and provide virtual test data. This removes wait times for real API calls to complete during automated builds. Consumer testing can verify that provider APIs meet expected contracts using mocks in the CI pipeline. This ensures the contract remains intact across code changes before deployment. Front-end/client code can scale release cycles faster than backend APIs by using mocks to simulate planned API behaviors before they are ready. + +## How mock responses work + +When the Mock Response middleware is configured for a specific endpoint, it terminates requests to the endpoint and generates an HTTP response that will be returned to the client as if it had come from the upstream service. No request will be passed to the upstream. The mock response to an API request should be designed to emulate how the service would respond to requests. To enable this, the content of the response can be configured to match the API contract for the service: you can set the HTTP status code, body and headers for the response. + +### Advanced mock responses with Tyk OAS + +When working with Tyk OAS APIs, Tyk Gateway can automatically parse the [examples and schema]({{< ref "product-stack/tyk-gateway/middleware/mock-response-openapi" >}}) in the OpenAPI description and use this to generate responses automatically depending on the [content of the request]({{< ref "product-stack/tyk-gateway/middleware/mock-response-tyk-oas#working-with-multiple-mock-responses-for-an-endpoint" >}}) + +### Middleware order and request processing + +When working with **Tyk OAS APIs** +- the mock response middleware is executed at the **end** of the request processing chain, immediately prior to the request being proxied to the upstream +- all other request processing middleware (e.g. authentication, request transforms) will be executed prior to the mock response. + +When working with **Tyk Classic APIs** +- the mock response middleware is executed at the **start** of the request processing chain +- an endpoint with mock response will not run any other request processing middleware and will be unauthenticated (keyless), automatically returning the mock response for any request + +
+ +If you're using Tyk OAS APIs, then you can find details and examples of how to configure the Mock Response middleware [here]({{< ref "product-stack/tyk-gateway/middleware/mock-response-tyk-oas" >}}). + +If you're using Tyk Classic APIs, then you can find details and examples of how to configure the Mock Response middleware [here]({{< ref "product-stack/tyk-gateway/middleware/mock-response-tyk-classic" >}}). + + diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-openapi.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-openapi.md new file mode 100644 index 00000000000..698995bf0c1 --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-openapi.md @@ -0,0 +1,152 @@ +--- +title: "Mock Responses using OpenAPI metadata" +date: 2024-01-31 +description: "Explains how the OpenAPI Specification can be used to generate mock responses" +tags: ["mock response", "mock", "middleware", "per-endpoint", "OpenAPI", "OAS"] +--- + +The [OpenAPI Specification](https://learn.openapis.org/specification/docs.html#adding-examples) includes metadata that can be used by automatic documentation generators to produce comprehensive reference guides for APIs. Most objects in the specification include a `description` field that can provide additional human-readable information that is fed into such documentation. Alongside the descriptions, some OpenAPI objects can have sample values listed in the OpenAPI Document that further enhance the generated documentation by giving representative content that the upstream service might provide in responses. + +The specification provides two different ways for an API developer to provide sample responses for an endpoint: +- `example`: a sample value that could be returned in a specific field in a response (see [below](#using-example-to-generate-a-mock-response)) +- `examples`: a list of key-value pairs comprising of `"exampleName":"value"` (see [below](#using-examples-to-generate-a-mock-response)) + +Tyk's mock response middleware can [automatically generate a response]({{< ref "product-stack/tyk-gateway/middleware/mock-response-tyk-oas#automatically-configuring-the-middleware-from-the-openapi-document" >}}) using the data provided in the OpenAPI description part of the Tyk OAS API Definition. + +If neither `example` nor `examples` are defined, Tyk can automatically create a mock response if a `schema` is defined that describes the format of the response as shown [below](#using-schema-to-generate-a-mock-response). + +{{< note success >}} +**Note** + +Note that `example` and `examples` are mutually exclusive within the OpenAPI Document for a field in the `responses` object: the developer cannot provide both for the same object. +
The content-type (e.g. `application/json`, `text/plain`) must be declared for each `example` or `examples` in the API description. +{{< /note >}} + +### Using `example` to generate a mock response + +``` json {hl_lines=["9-11"],linenos=true, linenostart=1} +{ + "paths": { + "/get": { + "get": { + "operationId": "getget", + "responses": { + "200": { + "content": { + "text/plain": { + "example": "Furkan" + } + }, + "description": "" + } + } + } + } + } +} +``` +In this extract from an OpenAPI description, a single `example` has been declared for a request to `GET /get` - the API developer indicates that such a call could return `HTTP 200` and the body value `Furkan` in plain text format. + +### Using `examples` to generate a mock response +``` json {hl_lines=["9-18"],linenos=true, linenostart=1} +{ + "paths": { + "/get": { + "get": { + "operationId": "getget", + "responses": { + "200": { + "content": { + "text/plain": { + "examples": { + "first-example": { + "value": "Jeff" + }, + "second-example": { + "value": "Laurentiu" + } + } + } + }, + "description": "" + } + } + } + } + } +} +``` +In this extract, the API developer also indicates that a call to `GET /get` could return `HTTP 200` but here provides two example body values `Jeff` and `Laurentiu`, again in plain text format. + +The `exampleNames` for these two values have been configured as `first-example` and `second-example` and can be used to [invoke the desired response]({{< ref "product-stack/tyk-gateway/middleware/mock-response-tyk-oas#working-with-multiple-mock-responses-for-an-endpoint" >}}) from a mocked endpoint. + +### Using `schema` to generate a mock response + +If there is no `example` or `examples` defined for an endpoint, Tyk will try to find a `schema` for the response. If there is a schema, it will be used to generate a mock response. Tyk can extract values from referenced or nested schema objects when creating the mock response. + +Response headers do not have standalone `example` or `examples` attributes, however they can have a `schema` - the Mock Response middleware will include these in the mock response if provided in the OpenAPI description. + +The schema properties may have an `example` field, in which case they will be used to build a mock response. If there is no `example` value in the schema then default values are used to build a response as follows: +- `string` > `"string"` +- `integer` > `0` +- `boolean` > `true` + +For example: +``` json {hl_lines=["10-13", "18-33"],linenos=true, linenostart=1} +{ + "paths": { + "/get": { + "get": { + "operationId": "getget", + "responses": { + "200": { + "headers": { + "X-Status": { + "schema": { + "type": "string", + "example": "Maciej" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "lastName": { + "example": "Petric", + "type": "string" + }, + "name": { + "example": "Andrei", + "type": "string" + }, + "id": { + "type": "integer" + } + } + } + } + }, + "description": "" + } + } + } + } + } +} +``` + +This partial OpenAPI description defines a schema for the `GET /get` endpoint that Tyk Gateway could use to generate this mock response: + +``` bash +HTTP/1.1 200 OK +X-Status: Maciej +Content-Type: application/json + +{ + "lastName": "Petric", + "name": "Andrei", + "id": 0 +} +``` \ No newline at end of file diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-tyk-classic.md new file mode 100644 index 00000000000..986fc88805e --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-tyk-classic.md @@ -0,0 +1,95 @@ +--- +title: Using the Mock Response middleware with Tyk Classic APIs +date: 2024-01-31 +description: "Using the Mock Response middleware with Tyk Classic APIs" +tags: ["mock response", "middleware", "per-endpoint", "Tyk Classic", "Tyk Classic API"] +--- + +The [Mock Response]({{< ref "product-stack/tyk-gateway/middleware/mock-response-middleware" >}}) middleware allows you to configure Tyk to return a response for an API endpoint without requiring an upstream service. This can be useful when creating a new API or making a development API available to an external team. + +When working with Tyk Classic APIs, this middleware is executed at the start of the request processing chain. Thus an endpoint with the mock response middleware will not be authenticated, will not process other middleware configured for the API (neither API nor endpoint level) and will have no analytics created. It will simply return the configured response for any request made to that endpoint. + +The middleware 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/mock-response-tyk-oas" >}}) page. + +## Configuring the middleware in the Tyk Classic API Definition +To enable mock response, you must first add the endpoint to a list - one of [allow list]({{< ref "product-stack/tyk-gateway/middleware/allow-list-middleware" >}}), [block list]({{< ref "product-stack/tyk-gateway/middleware/block-list-middleware" >}}) or [ignore authentication]({{< ref "product-stack/tyk-gateway/middleware/ignore-middleware" >}}). This will add a new object to the `extended_paths` section of your API definition - `white_list`, `black_list` or `ignored`. The mock response can then be configured within the `method_actions` element within the new object. + +The `white_list`, `black_list` and `ignored` objects all have the same structure and configuration as follows: +- `path`: the path to match on +- `method`: this should be blank +- `ignore_case`: if set to `true` then the path matching will be case insensitive +- `method_actions`: the configuration of the mock response + +The `method_actions` object should be configured as follows, with an entry created for each method on the path for which you wish to configure the mock response: +- `action`: this should be set to `reply` +- `code`: the HTTP status code to be provided with the response +- `headers`: the headers to inject with the response +- `body`: the payload to be returned as the body of the response + +For example: +``` json {linenos=true, linenostart=1} +{ + "extended_paths": { + "white_list": [ + { + "disabled": false, + "path": "/anything", + "method": "", + "ignore_case": false, + "method_actions": { + "GET": { + "action": "reply", + "code": 200, + "data": "This is the mock response body", + "headers": { + "X-Example-Header": "foobar" + } + } + } + } + ] + } +} +``` + +In this example the mock response middleware has been configured for requests to the `GET /anything` endpoint. The [allow list]({{< ref "product-stack/tyk-gateway/middleware/allow-list-middleware" >}}) middleware has been enabled for this endpoint and is case sensitive, so calls to `GET /Anything` will not return the mock response. + +A call to `GET /anything` would return: + +``` +HTTP/1.1 200 OK +X-Example-Header: foobar +Date: Wed, 31 Jan 2024 16:21:05 GMT +Content-Length: 30 +Content-Type: text/plain; charset=utf-8 + +This is the mock response body +``` + +## Configuring the middleware in the API Designer + +You can use the API Designer in the Tyk Dashboard to configure the Mock Response middleware for your Tyk Classic API by following these steps. + +#### Step 1: Add an endpoint for the path and configure a list plugin +For the mock response to be enabled, the endpoint must also be in a list. We recommend adding the path to an allow list by [selecting]({{< ref "product-stack/tyk-gateway/middleware/allow-list-tyk-classic#configuring-the-allow-list-in-the-api-designer" >}}) the **Whitelist** plugin. + +#### Step 2: Add the mock response plugin +Now select the **Mock response** plugin. + +{{< img src="/img/dashboard/endpoint-designer/mock-response.png" alt="Selecting the mock response middleware for a Tyk Classic API" >}} + +#### Step 3: Configure the middleware +Once you have selected the Mock response middleware for the endpoint, you can configure the HTTP status code, headers and body to be included in the response. Remember to click **ADD**, to add each header to the response. + +{{< img src="/img/dashboard/endpoint-designer/mock-response-config.png" alt="Configuring the mock response middleware for a Tyk Classic API" >}} + +#### Step 4: Save the API +Use the *save* or *create* buttons to save the changes and activate the mock response middleware. + +{{< note success >}} +**Note** + +For the mock response to be enabled, the endpoint must also be in a list. We recommend adding the path to an [allow list]({{< ref "advanced-configuration/transform-traffic/endpoint-designer#allowlist" >}}). If this isn't done, then the mock will not be saved when you save your API in the designer. +{{< /note >}} diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-tyk-oas.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-tyk-oas.md new file mode 100644 index 00000000000..3542cfe743f --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/mock-response-tyk-oas.md @@ -0,0 +1,430 @@ +--- +title: Using the Mock Response middleware with Tyk OAS APIs +date: 2024-01-31 +description: "Using the Mock Response middleware with Tyk OAS APIs" +tags: ["mock response", "middleware", "per-endpoint", "Tyk OAS", "Tyk OAS API"] +--- + +The [Mock Response]({{< ref "product-stack/tyk-gateway/middleware/mock-response-middleware" >}}) middleware allows you to configure Tyk to return a response for an API endpoint without requiring an upstream service. This can be useful when creating a new API or making a development API available to an external team. + +When working with Tyk OAS APIs, this middleware is executed at the end of the request processing chain immediately prior to the upstream proxy stage. Thus, any other request processing middleware - including authentication - will be run before the request reaches the mock response. + +The middleware 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. + +The Mock Response middleware has two modes of operation: +- with [manual mode](#manually-configuring-the-middleware-in-the-tyk-oas-api-definition), you can directly configure a response within the middleware in the Tyk extension (`x-tyk-api-gateway`) within the API definition. Tyk will give this response to all valid requests to the endpoint +- with [automatic mode](#automatically-configuring-the-middleware-from-the-openapi-document), Tyk will parse the [examples and schema]({{< ref "product-stack/tyk-gateway/middleware/mock-response-openapi" >}}) in the OpenAPI description and use this to generate responses automatically depending on the [content of the request](#working-with-multiple-mock-responses-for-an-endpoint) + +If you're using the legacy Tyk Classic APIs, then check out the [Tyk Classic]({{< ref "product-stack/tyk-gateway/middleware/mock-response-tyk-classic" >}}) page. + +## Manually configuring the middleware 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. + +The mock response middleware (`mockResponse`) 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). + +For basic operation, the `mockResponse` object has the following configuration: +- `enabled`: enable the middleware for the endpoint +- `code`: the HTTP status code to be provided with the response (this defaults to `200` if not set) +- `body`: the payload to be returned as the body of the response +- `headers`: the headers to inject with the response + +For example: +``` json {hl_lines=["39-49"],linenos=true, linenostart=1} +{ + "components": {}, + "info": { + "title": "example-mock-response1", + "version": "1.0.0" + }, + "openapi": "3.0.3", + "paths": { + "/anything": { + "get": { + "operationId": "anythingget", + "responses": { + "200": { + "description": "" + } + } + } + } + }, + "x-tyk-api-gateway": { + "info": { + "name": "example-mock-response1", + "state": { + "active": true + } + }, + "upstream": { + "url": "http://httpbin.org/" + }, + "server": { + "listenPath": { + "value": "/example-mock-response1/", + "strip": true + } + }, + "middleware": { + "operations": { + "anythingget": { + "mockResponse": { + "enabled": true, + "code": 200, + "body": "This is the mock response body", + "headers": [ + { + "name": "X-Example-Header", + "value": "foobar" + } + ] + } + } + } + } + } +} +``` + +In this example the mock response middleware has been configured for requests to the `GET /example-mock-response1/anything` endpoint. + +A call to `GET /example-mock-response1/anything` would return: + +``` +HTTP/1.1 200 OK +X-Example-Header: foobar +Content-Type: text/plain; charset=utf-8 + +This is the mock response body +``` + +The configuration above is a complete and valid Tyk OAS API Definition that you can import into Tyk to try out the mock response middleware. + +## Automatically configuring the middleware from the OpenAPI Document + +You can direct Tyk to configure the Mock Response middleware automatically from the examples and schema [defined]({{< ref "product-stack/tyk-gateway/middleware/mock-response-openapi" >}}) in the OpenAPI description. + +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. + +The mock response middleware (`mockResponse`) 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). + +For basic operation, the `mockResponse` object has the following configuration: +- `enabled`: enable the middleware for the endpoint +- `fromOASExamples`: an object used to instruct Tyk Gateway to return a response from the OpenAPI description + +The `fromOASExamples` object has the following configuration: +- `enabled`: enable the automatic configuration of mock response +- `code`: [optional] identifies which HTTP status code to be provided with the response (defaults to `200` if not set) +- `contentType`: [optional] identifies which response body type to use (defaults to `application/json` if not set) +- `exampleName`: [optional] the sample response to be returned from an `examples` list + +The three optional fields (`code`, `contentType`, `exampleName`) are used to identify which sample response should be returned by the mock if multiple sample responses are declared in the OpenAPI description. + +For example: +``` json {hl_lines=["15-24", "29-33", "59-67"],linenos=true, linenostart=1} +{ + "components": {}, + "info": { + "title": "example-mock-response2", + "version": "1.0.0" + }, + "openapi": "3.0.3", + "paths": { + "/anything": { + "get": { + "operationId": "anythingget", + "responses": { + "200": { + "content": { + "text/plain": { + "examples": { + "first-example": { + "value": "My favourite is pasta" + }, + "second-example": { + "value": "My second favourite is pizza" + } + } + } + }, + "description": "" + }, + "300": { + "content": { + "text/plain": { + "example": "There's too much choice" + } + }, + "description": "" + } + } + } + } + }, + "x-tyk-api-gateway": { + "info": { + "name": "example-mock-response2", + "state": { + "active": true + } + }, + "upstream": { + "url": "http://httpbin.org/" + }, + "server": { + "listenPath": { + "value": "/example-mock-response2/", + "strip": true + } + }, + "middleware": { + "operations": { + "anythingget": { + "mockResponse": { + "enabled": true, + "fromOASExamples": { + "enabled": true, + "code": 200, + "contentType": "text/plain", + "exampleName": "second-example" + } + } + } + } + } + } +} +``` + +In this example, the OpenAPI description declares three possible responses: two for HTTP 200 and one for HTTP 300. We have configured the Mock Response middleware to return the value defined for HTTP 200 (code) with `exampleName` set to "second-example". + +If you make a call to `GET /example-mock-response2/anything` the response will be: + +``` bash +HTTP/1.1 200 OK +Content-Type: text/plain +Date: Thu, 01 Feb 2024 12:31:50 GMT +Content-Length: 8 + +"My second favourite is pizza" +``` + +If you add `"code":300` in the `fromOASExamples` object, a call to `GET /example-mock-response2/anything` would instead respond as follows: + +``` bash +HTTP/1.1 300 Multiple Choices +Content-Type: text/plain +Date: Thu, 01 Feb 2024 12:35:45 GMT +Content-Length: 8 + +"There's too much choice" +``` + +{{< note success >}} +**Note** + +If multiple `examples` are defined in the OpenAPI description but no default `exampleName` is set in the middleware configuration `fromOASExamples` Tyk will select randomly from the multiple `examples`. Yes, that means the response may change with every request. You can [control which response](#working-with-multiple-mock-responses-for-an-endpoint) will be returned using special headers in the request. +{{< /note >}} + +The configuration above is a complete and valid Tyk OAS API Definition that you can import into Tyk to try out the mock response middleware. + +## Working with multiple mock responses for an endpoint + +When the mock response middleware in your Tyk OAS API is configured to return responses from the OpenAPI description within the API definition, you can invoke a specific response, overriding the defaults configured in the middleware, by providing specific headers in your request. + +To invoke a non-default response from a mocked endpoint, you must add *one or more* special headers to the request: +- `Accept`: This standard HTTP header will override the response content type (e.g. `application/json`, `text/plain`) +- `X-Tyk-Accept-Example-Code`: This will select the HTTP response code for which to return the example response (e.g. `400`) +- `X-Tyk-Accept-Example-Name`: This identifies which example to select from an `examples` list + +If an example response can’t be found for the configured `code`, `contentType` or `exampleName`, an HTTP 404 error will be returned to inform the client that there is no declared example for that configuration. + +For example: +``` json {hl_lines=["15-19", "22-39", "45-50", "53-55", "82-89"],linenos=true, linenostart=1} +{ + "components": {}, + "info": { + "title": "example-mock-response3", + "version": "1.0.0" + }, + "openapi": "3.0.3", + "paths": { + "/anything": { + "get": { + "operationId": "anythingget", + "responses": { + "200": { + "headers": { + "X-Status": { + "schema": { + "type": "boolean" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "lastName": { + "example": "Bar", + "type": "string" + }, + "name": { + "example": "Foo", + "type": "string" + }, + "id": { + "type": "integer" + } + } + } + } + }, + "description": "" + }, + "300": { + "headers": { + "X-Status": { + "schema": { + "type": "boolean", + "example": false + } + } + }, + "content": { + "text/plain": { + "example": "Baz" + } + }, + "description": "" + } + } + } + } + }, + "x-tyk-api-gateway": { + "info": { + "name": "example-mock-response3", + "state": { + "active": true + } + }, + "upstream": { + "url": "http://httpbin.org/" + }, + "server": { + "listenPath": { + "value": "/example-mock-response3/", + "strip": true + } + }, + "middleware": { + "operations": { + "anythingget": { + "mockResponse": { + "enabled": true, + "fromOASExamples": { + "enabled": true, + "code": 200, + "contentType": "application/json" + } + } + } + } + } + } +} +``` + +In this example, the OpenAPI document declares two possible responses: one for HTTP 200 and one for HTTP 300. We have configured the Mock Response middleware to return the value defined for HTTP 200 for which the body (content) is in JSON format and a custom header `X-Status` which will take the default value of `true`. + +You can trigger the mock response for HTTP 300 by adding the following headers to your request: + - `X-Tyk-Accept-Example-Code`: 300 + - `Accept`: text/plain + +This would return a plain text body and the `X-Status` header set to `false`. + +The configuration above is a complete and valid Tyk OAS API Definition that you can import into Tyk to try out the mock response middleware. + +## Configuring the middleware in the API Designer + +Adding a mock response to your API endpoints is easy when using the API Designer in the Tyk Dashboard, simply follow the steps appropriate to the configuration method you wish to use: + - [manual configuration](#manual-configuration) of the middleware config + - [automatic configuration](#automatic-configuration) from the OpenAPI description + +### Manual configuration + +##### 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 Mock Response middleware +Select **ADD MIDDLEWARE** and choose **Mock Response** middleware from the *Add Middleware* screen. + +{{< img src="/img/dashboard/api-designer/tyk-oas-mock.png" alt="Adding the Mock Response middleware" >}} + +##### Step 3: Configure the middleware +Select **Tyk Classic mock response** + +{{< img src="/img/dashboard/api-designer/tyk-oas-mock-added.png" alt="Mock Response middleware added to endpoint - select the configuration method you require" >}} + +This takes you to the middleware configuration screen where you can: +- choose the HTTP status code that you want Tyk Gateway to return +- select the content type +- add a description for your mock response +- define headers to be provided with the response +- define the body that will be returned in the response (note that this must be defined as a JSON schema) + +{{< img src="/img/dashboard/api-designer/tyk-oas-mock-manual.png" alt="Configuring the mock response" >}} + +Select **UPDATE MIDDLEWARE** to apply the change to the middleware configuration. + +##### Step 4: Save the API +Select **SAVE API** to apply the changes to your API. + +### Automatic configuration + +##### Step 1: Import OpenAPI Document containing sample responses or schema +Import your OpenAPI Document (from file, URL or by pasting the JSON into the text editor) configuring the **upstream URL** and **listen path**, and selecting **Auto-generate middleware to deliver mock responses**. + +Selecting this option will cause Tyk Dashboard to check for sample responses or schema in the OpenAPI description and will automatically add the Mock Response middleware for any endpoints that have suitable data. + +{{< img src="/img/dashboard/api-designer/tyk-oas-mock-auto-options.png" alt="Configuring the OpenAPI document import to create Mock Responses" >}} + +##### Step 2: Edit the Mock Response middleware +Select **EDIT** and then the **Mock Response** middleware from the **Endpoints** tab. This will take you to the Edit Middleware screen. Note that *Use mock response from Open API Specification* has been selected. + +{{< img src="/img/dashboard/api-designer/tyk-oas-mock-auto-edit.png" alt="Editing the Mock Response middleware" >}} + +##### Step 3: Configure the middleware +Tyk Dashboard will automatically have selected a valid HTTP response code from the drop-down. When you select a valid content-type for which a mock response is configured in the OpenAPI specification, the API Designer will display the associated response. + +{{< img src="/img/dashboard/api-designer/tyk-oas-mock-auto-select.png" alt="Mock Response middleware automatically configured from OpenAPI description" >}} + +Here you can edit the mock response: +- modify, add or delete Response Body examples (note that this must follow the selected content-type) +- choose a default Response Body example that will be provided (unless [overridden in the request]({{< ref "#working-with-multiple-mock-responses-for-an-endpoint" >}})) +- add a description for your mock response +- define headers to be provided with the response (note that these must be defined as a JSON schema) +- add a schema + +You can create and edit mock responses for multiple HTTP status codes by choosing a different status code from the drop down. + +Select **UPDATE MIDDLEWARE** to apply the change to the middleware configuration. + +##### Step 4: Save the API +Select **SAVE API** to apply the changes to your API. + +{{< note success >}} +**Note** + +Modifying the automatically configured Mock Response middleware will update the OpenAPI description part of your Tyk OAS API definition, as the detail of the mock response is not set in the `x-tyk-api-gateway` extension but is automatically generated in response to the particular request received to the endpoint. +{{< /note >}} + 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 00000000000..87a8adf48d2 --- /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 00000000000..544859e329a --- /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 00000000000..7ef3949195e --- /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 00000000000..9488b19b89b --- /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/product-stack/tyk-gateway/middleware/request-size-limit-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-size-limit-tyk-classic.md new file mode 100644 index 00000000000..ce69cd628fb --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-size-limit-tyk-classic.md @@ -0,0 +1,82 @@ +--- +title: Using the Request Size Limit middleware with Tyk Classic APIs +date: 2024-03-04 +description: "Using the Request Size Limit middleware with Tyk Classic APIs" +tags: ["request size limit", "size limit", "security", "middleware", "per-endpoint", "per-API", "Tyk Classic", "Tyk Classic API"] +--- + +The [request size limit]({{< ref "basic-config-and-security/control-limit-traffic/request-size-limits" >}}) middleware enables you to 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. + +This middleware 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-size-limit-tyk-oas" >}}) page. + +## Configuring the middleware in the Tyk Classic API Definition + +There are three different levels of granularity that can be used when configuring a request size limit. + - [system-wide]({{< ref "basic-config-and-security/control-limit-traffic/request-size-limits#applying-a-system-wide-size-limit" >}}): affecting all APIs deployed on the gateway + - [API-level]({{< ref "product-stack/tyk-gateway/middleware/request-size-limit-tyk-classic#applying-a-size-limit-for-a-specific-api" >}}): affecting all endpoints for an API + - [endpoint-level]({{< ref "product-stack/tyk-gateway/middleware/request-size-limit-tyk-classic#applying-a-size-limit-for-a-specific-endpoint" >}}): affecting a single API endpoint + +### Applying a size limit for a specific API + +You can configure a request size limit (in bytes) to an API by configuring the `global_size_limit` within the `version` element of the API Definition, for example: +``` +"global_size_limit": 2500 +``` + +A value of zero (default) means that no maximum is set and the API-level size limit check will not be performed. + +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 `HTTP 400 Request is too large`. + +### Applying a size limit for a specific endpoint + +The most granular control over request sizes is provided by the endpoint-level configuration. This limit will be applied after any Gateway-level or API-level size limits and is given in bytes. If this test fails, the Tyk Gateway will report `HTTP 400 Request is too large`. + +To enable the middleware you must add a new `size_limits` object to the `extended_paths` section of your API definition. + +The `size_limits` object has the following configuration: + - `path`: the path to match on + - `method`: the method to match on + - `size_limit`: the maximum size permitted for a request to the endpoint (in bytes) + +For example: +```.json {linenos=true, linenostart=1} +{ + "extended_paths": { + "size_limits": [ + { + "disabled": false, + "path": "/anything", + "method": "POST", + "size_limit": 100 + } + ] + } +} +``` + +In this example the endpoint-level Request Size Limit middleware has been configured for HTTP `POST` requests to the `/anything` endpoint. For any call made to this endpoint, Tyk will check the size of the payload (Request body) and, if it is larger than 100 bytes, will reject the request, returning `HTTP 400 Request is too large`. + +## Configuring the middleware in the API Designer + +You can use the API Designer in the Tyk Dashboard to configure a request size limit for your Tyk Classic API by following these steps. + +#### Step 1: Add an endpoint for the path and select the plugin +From the **Endpoint Designer** add an endpoint that matches the path for which you want to trigger the virtual endpoint. Select the **Request size limit** plugin. + +{{< img src="/img/2.10/request_size_limit.png" alt="Select middleware" >}} + +#### Step 2: Configure the middleware +Set the request size limit, in bytes. + +{{< img src="/img/2.10/request_size_settings.png" alt="Configure limit" >}} + +#### Step 3: Save the API +Use the *save* or *create* buttons to save the changes and activate the Virtual Endpoint middleware. + +{{< note success >}} +**Note** + +The Tyk Classic API Designer does not provide an option to configure `global_size_limit`, but you can do this from the Raw Definition editor. +{{< /note >}} \ No newline at end of file diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/request-size-limit-tyk-oas.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-size-limit-tyk-oas.md new file mode 100644 index 00000000000..21d3c6f09a0 --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/request-size-limit-tyk-oas.md @@ -0,0 +1,117 @@ +--- +title: Using the Request Size Limit middleware with Tyk OAS APIs +date: 2024-03-04 +description: "Using the Request Size Limit middleware with Tyk OAS APIs" +tags: ["request size limit", "size limit", "security", "middleware", "per-endpoint", "per-API", "Tyk OAS", "Tyk OAS API"] +--- + +The [request size limit]({{< ref "basic-config-and-security/control-limit-traffic/request-size-limits" >}}) middleware enables you to 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. + +The middleware 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-size-limit-tyk-classic" >}}) page. + +## Configuring the middleware in the Tyk OAS API Definition + +There are three different levels of granularity that can be used when configuring a request size limit. + - [system-wide]({{< ref "basic-config-and-security/control-limit-traffic/request-size-limits#applying-a-system-wide-size-limit" >}}): affecting all APIs deployed on the gateway + - [API-level]({{< ref "product-stack/tyk-gateway/middleware/request-size-limit-tyk-oas#applying-a-size-limit-for-a-specific-api" >}}): affecting all endpoints for an API + - [endpoint-level]({{< ref "product-stack/tyk-gateway/middleware/request-size-limit-tyk-oas#applying-a-size-limit-for-a-specific-endpoint" >}}): affecting a single API endpoint + +### Applying a size limit for a specific API + +The API-level rate limit has not yet been implemented for Tyk OAS APIs. + +You can work around this by implementing a combination of endpoint-level rate limits and [allow]({{< ref "advanced-configuration/transform-traffic/endpoint-designer#allowlist" >}}) or [block]({{< ref "advanced-configuration/transform-traffic/endpoint-designer#blocklist" >}}) lists. + +### Applying a size limit for a specific endpoint + +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. + +The virtual endpoint middleware (`requestSizeLimit`) 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 `requestSizeLimit` object has the following configuration: + - `enabled`: enable the middleware for the endpoint + - `value`: the maximum size permitted for a request to the endpoint (in bytes) + +For example: +```.json {hl_lines=["39-44"],linenos=true, linenostart=1} +{ + "components": {}, + "info": { + "title": "example-request-size-limit", + "version": "1.0.0" + }, + "openapi": "3.0.3", + "paths": { + "/anything": { + "post": { + "operationId": "anythingpost", + "responses": { + "200": { + "description": "" + } + } + } + } + }, + "x-tyk-api-gateway": { + "info": { + "name": "example-request-size-limit", + "state": { + "active": true, + "internal": false + } + }, + "upstream": { + "url": "http://httpbin.org/" + }, + "server": { + "listenPath": { + "value": "/example-request-size-limit/", + "strip": true + } + }, + "middleware": { + "operations": { + "anythingpost": { + "requestSizeLimit": { + "enabled": true, + "value": 100 + } + } + } + } + } +} +``` + +In this example the endpoint-level Request Size Limit middleware has been configured for HTTP `POST` requests to the `/anything` endpoint. For any call made to this endpoint, Tyk will check the size of the payload (Request body) and, if it is larger than 100 bytes, will reject the request, returning `HTTP 400 Request is too large`. + +The configuration above is a complete and valid Tyk OAS API Definition that you can import into Tyk to try out the virtual endpoint middleware. + +## Configuring the middleware in the API Designer + +Adding the Request Size Limit middleware to your API endpoints is easy when using the API Designer in the Tyk Dashboard, simply follow the following steps: + +#### Step 1: Add an endpoint for the path +From the **API Designer** add an endpoint that matches the path you want to rewrite. + +{{< 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 Size Limit middleware +Select **ADD MIDDLEWARE** and choose the **Request Size Limit** middleware from the *Add Middleware* screen. + +{{< img src="/img/dashboard/api-designer/tyk-oas-request-size-limit.png" alt="Adding the Request Size Limit middleware" >}} + +#### Step 3: Configure the middleware +Now you can set the **size limit** that the middleware should enforce - remember that this is given in bytes. + +{{< img src="/img/dashboard/api-designer/tyk-oas-request-size-limit-config.png" alt="Setting the size limit that should be enforced" >}} + +#### Step 4: Save the API +Select **ADD MIDDLEWARE** to save the middleware configuration. Remember to select **SAVE API** to apply the changes to your API. diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/response-header-tyk-oas.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/response-header-tyk-oas.md index e5b69d937e1..ee4a523886f 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/response-header-tyk-oas.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/response-header-tyk-oas.md @@ -193,23 +193,24 @@ Then select **NEW HEADER** as appropriate to add or remove a header from API res ### Adding an endpoint level transform -##### Step 1: Add an endpoint for the path and select the Response Header Transform middleware -From the **API Designer** add an endpoint that matches the path for which you want to modify the response. +##### 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 Response Header Transform middleware Select **ADD MIDDLEWARE** and choose the **Response Header Transform** middleware from the *Add Middleware* screen. {{< img src="/img/dashboard/api-designer/tyk-oas-add-response-header.png" alt="Adding the URL Rewrite middleware" >}} -##### Step 2: Configure header transformation +##### Step 3: Configure header transformation Select **NEW HEADER** to configure a header to be added to or removed from the response, you can add multiple headers to either list by selecting **NEW HEADER** again. {{< img src="/img/dashboard/api-designer/tyk-oas-response-header.png" alt="Configuring the rewrite rules for Advanced Triggers" >}} {{< img src="/img/dashboard/api-designer/tyk-oas-response-header-new.png" alt="Configuring the Response Header Transform" >}} -##### Step 3: Save the API +##### Step 4: Save the API Select **ADD MIDDLEWARE** to save the middleware configuration. Remember to select **SAVE API** to apply the changes. diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/url-rewrite-tyk-oas.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/url-rewrite-tyk-oas.md index dbb271c80bf..c1927734be7 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/middleware/url-rewrite-tyk-oas.md +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/url-rewrite-tyk-oas.md @@ -269,8 +269,8 @@ The configuration above is a complete and valid Tyk OAS API Definition that you Adding and configuring the URL rewrite feature to your API endpoints is easy when using the API Designer in the Tyk Dashboard, simply follow the following steps: -#### Step 1: Add an endpoint for the path and select the URL rewrite middleware -From the **API Designer** add an endpoint that matches the path you want to rewrite. +#### 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" >}} @@ -278,20 +278,20 @@ From the **API Designer** add an endpoint that matches the path you want to rewr {{< 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 URL Rewrite middleware Select **ADD MIDDLEWARE** and choose the **URL Rewrite** middleware from the *Add Middleware* screen. {{< img src="/img/dashboard/api-designer/tyk-oas-add-url-rewrite.png" alt="Adding the URL Rewrite middleware" >}} -#### Step 2: Configure the basic trigger +#### Step 3: Configure the basic trigger Add the match pattern and the new URL to configure the basic trigger rule. {{< img src="/img/dashboard/api-designer/tyk-oas-url-rewrite-basic.png" alt="Configuring the rewrite rule for the Basic Trigger" >}} -#### Step 3: Optionally configure advanced triggers +#### Step 4: Optionally configure advanced triggers You can optionally apply advanced triggers by selecting **ADD TRIGGER** for each trigger you wish to configure. For each advanced trigger you can add one or more rules, selecting **ADD RULE** to add the second, third, etc. {{< img src="/img/dashboard/api-designer/tyk-oas-url-rewrite-advanced.png" alt="Configuring the rewrite rules for Advanced Triggers" >}} -#### Step 4: Save the API +#### Step 5: Save the API Select **ADD MIDDLEWARE** to save the middleware configuration. Remember to select **SAVE API** to apply the changes. - diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/validate-request-middleware.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/validate-request-middleware.md new file mode 100644 index 00000000000..b54566c152f --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/validate-request-middleware.md @@ -0,0 +1,47 @@ +--- +title: Request Validation middleware +date: 2024-02-02 +description: "Detail of the Request Validation middleware" +tags: ["request validation", "validate request", "security", "middleware", "per-endpoint"] +aliases: + - /transform-traffic/validate-json/ + - /getting-started/key-concepts/request-validation/ +--- + +Requests to your upstream services should meet the contract that you have defined for those APIs. Checking the content and format of incoming requests before they are passed to the upstream APIs can avoid unexpected errors and provide additional security to those services. Tyk's request validation middleware provides a way to validate the presence, correctness and conformity of HTTP requests to make sure they meet the expected format required by the upstream API endpoints. + +Request validation enables cleaner backend APIs, better standardisation across consumers, easier API evolution and reduced failure risk leading to higher end-to-end reliability. + +## When to use the Request Validation middleware + +#### Improving security of upstream services +Validating incoming requests against a defined schema protects services from unintended consequences arising from bad input, such as SQL injection or buffer overflow errors, or other unintended failures caused by missing parameters or invalid data types. Offloading this security check to the API Gateway provides an early line of defence as potentially bad requests are not proxied to your upstream services. + +#### Offloading contract enforcement +You can ensure that client requests adhere to a defined contract specifying mandatory headers or parameters before sending requests upstream. Performing these validation checks in the API Gateway allows API developers to focus on core domain logic. + +#### Supporting data transformation +Validation goes hand-in-hand with request [header]({{< ref "transform-traffic/request-headers" >}}) and [body]({{< ref "transform-traffic/request-body" >}}) transformation by ensuring that a request complies with the expected schema prior to transformation. For example, you could validate that a date parameter is present, then transform it into a different date format as required by your upstream API dynamically on each request. + +## How request validation works + +The incoming request is compared with a defined schema, which is a structured description of the expected format for requests to the endpoint. This request schema defines the required and optional elements such as headers, path/query parameters, payloads and their data types. It acts as a contract for clients. + +If the incoming request does not match the schema, it will be rejected with an `HTTP 422 Unprocessable Entity` error. This error code can be customised if required. + +When using [Tyk OAS APIs]({{< ref "product-stack/tyk-gateway/middleware/validate-request-tyk-oas" >}}), request validation is performed by the `Validate Request` middleware which can be enabled per-endpoint. The schema against which requests are compared is defined in the OpenAPI description of the endpoint. All elements of the request can have a `schema` defined in the OpenAPI description so requests to Tyk OAS APIs can be validated for headers, path/query parameters and body (payload). + +When using the legacy [Tyk Classic APIs]({{< ref "product-stack/tyk-gateway/middleware/validate-request-tyk-classic" >}}), request validation is performed by the `Validate JSON` middleware which can be enabled per-endpoint. The schema against which requests are compared is defined in the middleware configuration and is limited to the request body (payload). Request headers and path/query parameters cannot be validated when using Tyk Classic APIs. + +
+ +If you're using Tyk OAS APIs, then you can find details and examples of how to configure the request validation middleware [here]({{< ref "product-stack/tyk-gateway/middleware/validate-request-tyk-oas" >}}). + +If you're using Tyk Classic APIs, then you can find details and examples of how to configure the request validation middleware [here]({{< ref "product-stack/tyk-gateway/middleware/validate-request-tyk-classic" >}}). + + + \ No newline at end of file diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/validate-request-tyk-classic.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/validate-request-tyk-classic.md new file mode 100644 index 00000000000..87f1a99158a --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/validate-request-tyk-classic.md @@ -0,0 +1,82 @@ +--- +title: Using the Request Validation middleware with Tyk Classic APIs +date: 2024-02-02 +description: "Using the Request Validation middleware with Tyk Classic APIs" +tags: ["request validation", "validate JSON", "middleware", "per-endpoint", "Tyk Classic", "Tyk Classic API"] +aliases: + - /advanced-configuration/transform-traffic/validate-json +--- + +The [request validation]({{< ref "product-stack/tyk-gateway/middleware/validate-request-middleware" >}}) middleware provides a way to validate the presence, correctness and conformity of HTTP requests to make sure they meet the expected format required by the upstream API endpoints. + +When working with legacy Tyk Classic APIs, request validation is performed by the `Validate JSON` middleware which can be enabled per-endpoint. The schema against which requests are compared is defined in the middleware configuration and is limited to the request body (payload). Request headers and path/query parameters cannot be validated when using Tyk Classic APIs. + +This middleware 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/validate-request-tyk-oas" >}}) page. + +## Configuring the middleware in the Tyk Classic API Definition + +To enable the middleware you must add a new `validate_json` object to the `extended_paths` section of your API definition. + +The `validate_json` object has the following configuration: +- `path`: the path to match on +- `method`: this method to match on +- `schema`: the [JSON schema](https://json-schema.org/understanding-json-schema/basics) against which the request body will be compared +- `error_response_code`: the HTTP status code that will be returned if validation fails (defaults to `422 Unprocessable Entity`) + +For example: +```json {linenos=true, linenostart=1} +{ + "extended_paths": { + "validate_json": [ + { + "disabled": false, + "path": "/register", + "method": "POST", + "schema": { + "type": "object", + "properties": { + "firstname": { + "type": "string", + "description": "The person's first name" + }, + "lastname": { + "type": "string", + "description": "The person's last name" + } + } + }, + "error_response_code": 422 + } + ] + } +} +``` + +In this example the Validate JSON middleware has been configured for requests to the `POST /register` endpoint. For any call made to this endpoint, Tyk will compare the request body with the schema and, if it does not match, the request will be rejected with the error code `HTTP 422 Unprocessable Entity`. + +{{< note success >}} + +**Note** + +The Validate JSON middleware supports JSON Schema `draft-04`. Using another version will return an `unsupported schema error, unable to validate` error in the Tyk Gateway logs. + +{{< /note >}} + +## Configuring the middleware in the API Designer + +You can use the API Designer in the Tyk Dashboard to configure the request validation middleware for your Tyk Classic API by following these steps. + +#### Step 1: Add an endpoint for the path and select the plugin +From the **Endpoint Designer** add an endpoint that matches the path for which you want to allow access. Select the **Validate JSON** plugin. + +{{< img src="/img/2.10/validate_json.png" alt="validate json plugin" >}} + +#### Step 2: Configure the middleware +Once you have selected the request validation middleware for the endpoint, you can select an error code from the drop-down list (if you don't want to use the default `422 Unprocessable Entity`) and enter your JSON schema in the editor. + +{{< img src="/img/dashboard/endpoint-designer/validate-json-schema.png" alt="Adding schema to the Validate JSON middleware" >}} + +#### Step 3: Save the API +Use the *save* or *create* buttons to save the changes and activate the Validate JSON middleware. diff --git a/tyk-docs/content/product-stack/tyk-gateway/middleware/validate-request-tyk-oas.md b/tyk-docs/content/product-stack/tyk-gateway/middleware/validate-request-tyk-oas.md new file mode 100644 index 00000000000..8ec6c68cc7e --- /dev/null +++ b/tyk-docs/content/product-stack/tyk-gateway/middleware/validate-request-tyk-oas.md @@ -0,0 +1,181 @@ +--- +title: Using the Request Validation middleware with Tyk OAS APIs +date: 2024-02-02 +description: "Using the Request Validation middleware with Tyk OAS APIs" +tags: ["request validation", "validate request", "middleware", "per-endpoint", "Tyk OAS", "Tyk OAS API"] +--- + +The [request validation]({{< ref "product-stack/tyk-gateway/middleware/validate-request-middleware" >}}) middleware provides a way to validate the presence, correctness and conformity of HTTP requests to make sure they meet the expected format required by the upstream API endpoints. + +The middleware 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/validate-request-tyk-classic" >}}) page. + +## Request schema in OpenAPI Specification + +The OpenAPI Specification supports the definition of a [schema](https://learn.openapis.org/specification/content.html#the-schema-object) to describe and limit the content of any field in an API request or response. + +Tyk's request validation middleware automatically parses the schema for the request in the OpenAPI description part of the Tyk OAS API Definition and uses this to compare against the incoming request. + +An OpenAPI schema can reference other schemas defined elsewhere, letting you write complex validations very efficiently since you don’t need to re-define the validation for a particular object every time you wish to refer to it. Tyk only supports local references to schemas (within the same OpenAPI document). + +As explained in the OpenAPI [documentation](https://learn.openapis.org/specification/parameters.html), the structure of an API request is described by two components: +- parameters (headers, query parameters, path parameters) +- request body (payload) + +### Request parameters + +The `parameters` field in the OpenAPI description is an array of [parameter objects](https://swagger.io/docs/specification/describing-parameters/) that each describe one parameter shared by all operations on that path. Here, an operation is defined as a combination of HTTP method and path, or, as Tyk calls it, an endpoint. Each `parameter` has two mandatory fields: +- `in`: the location of the parameter (`path`, `query`, `header`) +- `name`: a unique identifier within that location (i.e. no duplicate header names for a given operation/endpoint) + +There are also optional `description` and `required` fields. + +For each parameter, a schema can be declared that defines the `type` of data that can be stored (e.g. `boolean`, `string`) and any `example` or `default` values. + +### Request body + +The `requestBody` field in the OpenAPI description is a [Request Body Object](https://swagger.io/docs/specification/describing-request-body/). This has two optional fields (`description` and `required`) plus the `content` section which allows you to define a schema for the expected payload. Different schemas can be declared for different media types that are identified by content-type (e.g. `application/json`, `application/xml` and `text/plain`). + +## Configuring the request validation middleware + +The request validation middleware does not require configuration when working with Tyk OAS APIs. If it is [enabled](#enabling-the-request-validation-middleware) for an endpoint, then the middleware will automatically validate requests made to that endpoint against the schema defined in the API definition. The default response, if validation fails, is for Tyk Gateway to reject the request with an `HTTP 422 Unprocessable Entity` response. If you want to return a different HTTP status code, this can be set when enabling the middleware. + +## Enabling the request validation middleware + +When you create a Tyk OAS API by importing your OpenAPI description, you can instruct Tyk to enable request validation [automatically](#automatically-enabling-the-request-validation-middleware) for all endpoints with defined schemas. If you are creating your API without import, or if you only want to enable request validation for some endpoints, you can [manually enable](#manually-enabling-the-request-validation-middleware) the middleware in the Tyk OAS API definition. + +### Automatically enabling the request validation middleware + +The request validation middleware can be enabled for all endpoints that have defined schemas when [importing]({{< ref "getting-started/using-oas-definitions/import-an-oas-api#tutorial-5-create-an-api-that-validates-the-request-payload" >}}) an OpenAPI Document to create a Tyk OAS API. +- if you are using the `POST /apis/oas/import` endpoint in the [Tyk Dashboard API]({{< ref "tyk-dashboard-api" >}}) or [Tyk Gateway API]({{< ref "tyk-gateway-api" >}}) then you can do this by setting the `validateRequest=true` query parameter +- if you are using the API Designer, select the **Auto-generate middleware to validate requests** option on the **Import API** screen + +{{< img src="/img/dashboard/api-designer/tyk-oas-validate-request-import.png" alt="Select the option during OpenAPI import to validate requests" >}} + +If you want to adjust the configuration, for example to remove validation from specific endpoints or to change the HTTP status code returned on error, you can update the API definition as described [here](#manual-activation-of-request-validation-middleware). + +### Manually enabling the request validation middleware + +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. + +The request validation middleware (`validateRequest`) 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`. The `operationId` for an endpoint can be found within the `paths` section of your [OpenAPI specification](https://swagger.io/docs/specification/paths-and-operations/?sbsearch=operationIds). + +The `validateRequest` object has the following configuration: +- `enabled`: enable the middleware for the endpoint +- `errorResponseCode`: [optional] the HTTP status code to be returned if validation fails (this defaults to `HTTP 422 Unprocessable Entity` if not set) + +For example: +```json {hl_lines=["69-72"],linenos=true, linenostart=1} +{ + "components": {}, + "info": { + "title": "example-validate-request", + "version": "1.0.0" + }, + "openapi": "3.0.3", + "paths": { + "/anything": { + "get": { + "operationId": "anythingget", + "parameters": [ + { + "in": "header", + "name": "X-Security", + "required": true, + "schema": { + "type": "boolean" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "properties": { + "firstname": { + "description": "The person's first name", + "type": "string" + }, + "lastname": { + "description": "The person's last name", + "type": "string" + } + }, + "type": "object" + } + } + } + }, + "responses": { + "200": { + "description": "" + } + } + } + } + }, + "x-tyk-api-gateway": { + "info": { + "name": "example-validate-request", + "state": { + "active": true + } + }, + "upstream": { + "url": "http://httpbin.org/" + }, + "server": { + "listenPath": { + "value": "/example-validate-request/", + "strip": true + } + }, + "middleware": { + "operations": { + "anythingget": { + "validateRequest": { + "enabled": true, + "errorResponseCode": 400 + } + } + } + } + } +} +``` + +In this example the request validation middleware has been configured for requests to the `GET /anything` endpoint. The middleware will check for the existence of a header named `X-Security` and the request body will be validated against the declared schema. If there is no match, the request will be rejected and Tyk will return `HTTP 400` (as configured in `errorResponseCode`). + +The configuration above is a complete and valid Tyk OAS API Definition that you can import into Tyk to try out the request validation middleware. + +## Configuring the middleware in the API Designer + +Adding and configuring Request Validation for 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 Validate Request middleware +Select **ADD MIDDLEWARE** and choose **Validate Request** from the *Add Middleware* screen. + +{{< img src="/img/dashboard/api-designer/tyk-oas-validate-request.png" alt="Adding the Validate Request middleware" >}} + +The API Designer will show you the request body and request parameters schema detected in the OpenAPI description of the endpoint. + +{{< img src="/img/dashboard/api-designer/tyk-oas-validate-request-added.png" alt="Validate Request middleware schema is automatically populated" >}} + +#### Step 3: Configure the middleware +If required, you can select an alternative HTTP status code that will be returned if request validation fails. + +{{< img src="/img/dashboard/api-designer/tyk-oas-validate-request-config.png" alt="Configuring the Request Validation error resposne" >}} + +#### Step 4: Save the API +Select **ADD MIDDLEWARE** to save the middleware configuration. Remember to select **SAVE API** to apply the changes. diff --git a/tyk-docs/content/product-stack/tyk-gateway/release-notes/version-4.3.md b/tyk-docs/content/product-stack/tyk-gateway/release-notes/version-4.3.md index a97be37f2b0..f911ee66f2c 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/release-notes/version-4.3.md +++ b/tyk-docs/content/product-stack/tyk-gateway/release-notes/version-4.3.md @@ -10,13 +10,13 @@ aliases: #### Mock Responses with Tyk OAS API Definitions -Does your Tyk OAS API Definition define examples or a schema for your path responses? If so, starting with Tyk v4.3, Tyk can use those configurations to mock your API responses, enabling your teams to integrate easily without being immediately dependent on each other. Check it out! [Mock Responses Documentation]({{< ref "/content/getting-started/using-oas-definitions/mock-response.md" >}}) +Does your Tyk OAS API Definition define examples or a schema for your path responses? If so, starting with Tyk v4.3, Tyk can use those configurations to mock your API responses, enabling your teams to integrate easily without being immediately dependent on each other. Check it out! [Mock Responses Documentation]({{< ref "product-stack/tyk-gateway/middleware/mock-response-middleware" >}}) #### External OAuth - 3rd party OAuth IDP integration If you’re using a 3rd party IDP to generate tokens for your OAuth applications, Tyk can now validate the generated tokens by either performing JWT validation or by communicating with the authorisation server and executing token introspection. -This can be achieved by configuring the new External OAuth authentication mechanism. Find out more here [External OAuth Integration]({{< ref "/content/basic-config-and-security/security/authentication-authorization/ext-oauth-middleware.md" >}}) +This can be achieved by configuring the new External OAuth authentication mechanism. Find out more here [External OAuth Integration]({{< ref "basic-config-and-security/security/authentication-authorization/ext-oauth-middleware" >}}) #### Updated the Tyk Gateway version of Golang, to 1.16. @@ -31,7 +31,7 @@ Note that if the CommonName is an invalid host name, it's always ignored, regard 4.3 adds two important features that improve security settings for GraphQL APIs in Tyk. 1. Ability to turn on/off introspection - this feature allows much more control over what consumers are able to do when interacting with a GraphQL API. In cases where introspection is not desirable, API managers can now disallow it. The setting is done on API key level, which means API providers will have very granular control over who can and who cannot introspect the API. -2. Support for allow list in field-based permissions - so far Tyk was offering field-based permissions as a “block list” only. That meant that any new field/query added to a graph was by default accessible for all consumers until API manager explicitly blocked it on key/policy level. Adding support for “allow list” gives APi managers much more control over changing schemas and reduces the risk of unintentionally exposing part of the graph that are not ready for usage. See [Introspection]({{< ref "/content/graphql/introspection.md" >}}) for more details. +2. Support for allow list in field-based permissions - so far Tyk was offering field-based permissions as a “block list” only. That meant that any new field/query added to a graph was by default accessible for all consumers until API manager explicitly blocked it on key/policy level. Adding support for “allow list” gives APi managers much more control over changing schemas and reduces the risk of unintentionally exposing part of the graph that are not ready for usage. See [Introspection]({{< ref "graphql/introspection" >}}) for more details. ## Changelog @@ -71,9 +71,9 @@ Tyk Gateway 4.3 ([docker images](https://hub.docker.com/r/tykio/tyk-gateway/tags ## Upgrade process -Follow the [standard upgrade guide]({{< ref "/content/upgrading-tyk.md" >}}), there are no breaking changes in this release. +Follow the [standard upgrade guide]({{< ref "upgrading-tyk" >}}), there are no breaking changes in this release. -If you want switch from MongoDB to SQL, you can [use our migration tool]({{< ref "/content/planning-for-production/database-settings/postgresql.md#migrating-from-an-existing-mongodb-instance" >}}), but keep in mind that it does not yet support the migration of your analytics data. +If you want switch from MongoDB to SQL, you can [use our migration tool]({{< ref "planning-for-production/database-settings/postgresql#migrating-from-an-existing-mongodb-instance" >}}), but keep in mind that it does not yet support the migration of your analytics data. {{< note success >}} **Note** diff --git a/tyk-docs/content/product-stack/tyk-gateway/release-notes/version-5.0.md b/tyk-docs/content/product-stack/tyk-gateway/release-notes/version-5.0.md index e69fa4c45e5..8120a31902a 100644 --- a/tyk-docs/content/product-stack/tyk-gateway/release-notes/version-5.0.md +++ b/tyk-docs/content/product-stack/tyk-gateway/release-notes/version-5.0.md @@ -121,7 +121,7 @@ Tyk’s OSS users can now make use of extensive [custom middleware](https://tyk. [Versioning your Tyk OAS APIs]({{< ref "getting-started/key-concepts/oas-versioning" >}}) is easier than ever, with the Tyk OSS Gateway now looking after the maintenance of the list of versions associated with the base API for you; we’ve also added a new endpoint on the Tyk API that will return details of the versions for a given API. -We’ve improved support for [OAS Mock Responses]({{< ref "getting-started/using-oas-definitions/mock-response" >}}), with the Tyk OAS API definition now allowing you to register multiple Mock Responses in a single API, providing you with increased testing flexibility. +We’ve improved support for [OAS Mock Responses]({{< ref "product-stack/tyk-gateway/middleware/mock-response-middleware" >}}), with the Tyk OAS API definition now allowing you to register multiple Mock Responses in a single API, providing you with increased testing flexibility. Of course, we’ve also addressed some bugs and usability issues as part of our ongoing ambition to make Tyk OAS API the best way for you to create and manage your APIs. diff --git a/tyk-docs/content/transform-traffic/request-headers.md b/tyk-docs/content/transform-traffic/request-headers.md index f2f451131ed..f7bcddc48aa 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 26a7d7ae1a5..951e02ce763 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 @@ -1071,14 +1095,6 @@ menu: path: /getting-started/key-concepts/authentication category: Page show: True - - title: "Mock Response" - path: /getting-started/using-oas-definitions/mock-response - category: Page - show: True - - title: "Request Validation" - path: /getting-started/key-concepts/request-validation - category: Page - show: True - title: "Paths" path: /getting-started/key-concepts/paths category: Page @@ -1428,9 +1444,21 @@ menu: category: Page show: True - title: "Request Size Limits" - path: /basic-config-and-security/control-limit-traffic/request-size-limits - category: Page + category: Directory show: True + menu: + - title: "Overview" + path: /basic-config-and-security/control-limit-traffic/request-size-limits + category: Page + show: True + - title: "Tyk OAS configuration" + path: /product-stack/tyk-gateway/middleware/request-size-limit-tyk-oas + category: Page + show: True + - title: "Tyk Classic configuration" + path: /product-stack/tyk-gateway/middleware/request-size-limit-tyk-classic + category: Page + show: True - title: "Request Throttling" path: /basic-config-and-security/control-limit-traffic/request-throttling category: Page @@ -1455,10 +1483,22 @@ menu: path: /basic-config-and-security/reduce-latency/caching/global-cache/ category: Page show: True - - title: "Advanced Caching" - path: /basic-config-and-security/reduce-latency/caching/advanced-cache/ - category: Page + - title: "Endpoint Caching" + category: Directory show: True + menu: + - title: "Overview" + path: /basic-config-and-security/reduce-latency/caching/advanced-cache/ + category: Page + show: True + - title: "Tyk OAS configuration" + path: /product-stack/tyk-gateway/middleware/endpoint-cache-tyk-oas + category: Page + show: True + - title: "Tyk Classic configuration" + path: /product-stack/tyk-gateway/middleware/endpoint-cache-tyk-classic + category: Page + show: True - title: "Upstream Cache Control" path: /basic-config-and-security/reduce-latency/caching/upstream-controlled-cache/ category: Page @@ -1587,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 @@ -1623,10 +1687,42 @@ menu: path: /advanced-configuration/transform-traffic/soap-rest category: Page show: True - - title: "Validate JSON" - path: /advanced-configuration/transform-traffic/validate-json - category: Page + - title: "Request Validation" + category: Directory show: True + menu: + - title: "Overview" + path: /product-stack/tyk-gateway/middleware/validate-request-middleware + category: Page + show: True + - title: "Tyk OAS configuration" + path: /product-stack/tyk-gateway/middleware/validate-request-tyk-oas + category: Page + show: True + - title: "Tyk Classic configuration" + path: /product-stack/tyk-gateway/middleware/validate-request-tyk-classic + category: Page + show: True + - title: "Mock Response" + category: Directory + show: True + menu: + - title: "Overview" + path: /product-stack/tyk-gateway/middleware/mock-response-middleware + category: Page + show: True + - title: "Mock response with OAS" + path: /product-stack/tyk-gateway/middleware/mock-response-openapi + category: Page + show: True + - title: "Tyk OAS configuration" + path: /product-stack/tyk-gateway/middleware/mock-response-tyk-oas + category: Page + show: True + - title: "Tyk Classic configuration" + path: /product-stack/tyk-gateway/middleware/mock-response-tyk-classic + category: Page + show: True - title: "URL Rewriting" category: Directory show: True