diff --git a/en/docs/ai-gateway/README.md b/en/docs/ai-gateway/README.md index 0c57b288..a7094c2f 100644 --- a/en/docs/ai-gateway/README.md +++ b/en/docs/ai-gateway/README.md @@ -16,18 +16,18 @@ content_type: "overview" A gateway for managing and securing AI traffic, including Large Language Model (LLM) APIs and Model Context Protocol (MCP) servers. -## Quick Start +## Quick start - [LLM Quick Start Guide](llm-proxy/quick-start-guide.md) - Set up the gateway and route traffic to LLM providers like OpenAI - [MCP Quick Start Guide](mcp-proxy/quick-start-guide.md) - Set up the gateway and route traffic to MCP servers -## Key Concepts +## Key concepts -### LLM Provider Template +### LLM provider template An LLM Provider Template defines the characteristics and behaviors specific to an AI service provider, such as OpenAI, Azure OpenAI, or other LLM platforms. It describes how the gateway should interpret and extract usage and operational metadata, including prompt, completion, total, and remaining token information, as well as request and response model metadata. -Following templates are shipped out-of-the-box +The following templates are shipped out-of-the-box: - OpenAI - Azure OpenAI @@ -36,7 +36,7 @@ Following templates are shipped out-of-the-box - Azure AI Foundry - Gemini -### LLM Provider +### LLM provider An LLM Provider represents a connection to an AI backend service such as OpenAI, Azure OpenAI, or other LLM APIs. Platform administrators configure LLM Providers to define: @@ -49,15 +49,15 @@ An LLM Provider represents a connection to an AI backend service such as OpenAI, Once configured, the LLM Provider allows traffic to flow through the gateway to the AI backend. -### LLM Proxy +### LLM proxy -An LLM Proxy allows developers to create custom API endpoints that consume an LLM Provider, while inheriting administrator-enforced access control, budgeting and organization-wide policies defined at the provider level. Each proxy gets its own URL context (e.g., `/assistant`) and can have its own policies applied. This enables: +An LLM Proxy allows developers to create custom API endpoints that consume an LLM Provider, while inheriting administrator-enforced access control, budgeting, and organization-wide policies defined at the provider level. Each proxy gets its own URL context (e.g., `/assistant`) and can have its own policies applied. This enables: - Multiple AI applications to share a single LLM Provider - Per-application policies such as prompt management and guardrails - Separation between platform administration and application development -### MCP Proxy +### MCP proxy An MCP Proxy routes Model Context Protocol traffic to MCP servers. MCP is a protocol that enables AI assistants to interact with external tools and data sources. With MCP Proxies, you can: @@ -65,7 +65,7 @@ An MCP Proxy routes Model Context Protocol traffic to MCP servers. MCP is a prot - Apply authentication and access control to MCP traffic - Manage multiple MCP servers from a single control plane -## Default Ports +## Default ports | Port | Service | Description | |------|---------|-------------| diff --git a/en/docs/ai-gateway/ai-gateway-rest-api/authentication.md b/en/docs/ai-gateway/ai-gateway-rest-api/authentication.md index 63e56f1a..ac3e4565 100644 --- a/en/docs/ai-gateway/ai-gateway-rest-api/authentication.md +++ b/en/docs/ai-gateway/ai-gateway-rest-api/authentication.md @@ -1,5 +1,5 @@ --- -title: "Authentication and Authorization in Gateway Controller" +title: "Authentication and authorization in Gateway Controller" description: "Configure Basic Auth or JWT/IDP authentication and role-based authorization for the AI Gateway Controller REST API." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/ai-gateway-rest-api/authentication/ md_url: https://wso2.com/api-platform/docs/ai-gateway/ai-gateway-rest-api/authentication.md @@ -12,23 +12,23 @@ last_updated: 2026-06-16 content_type: "how-to" --- -# Authentication & Authorization in Gateway Controller +# Authentication and authorization in Gateway Controller ## Overview The Gateway Controller REST API (the control-plane API used to manage gateway configuration) can be protected using either locally configured users (Basic Auth) or an external Identity Provider (JWT validation via JWKS). Authorization is role-based and enforced per API route. -## How It Works +## How it works -### Authentication (Who are you?) +### Authentication (who are you?) You can enable one (or both) of the following: - **Basic Auth (local users)**: Define usernames/passwords and assign local roles. -- **IDP/JWT (external users)**: Validate incoming JWTs using `jwks_url` optionally `issuer`. +- **IDP/JWT (external users)**: Validate incoming JWTs using `jwks_url` and optionally `issuer`. -**No Authentication (open access)**: If BOTH `basic.enabled` and `idp.enabled` are set to `false`, all requests to the gateway controller are allowed without authentication. +**No Authentication (open access)**: If both `basic.enabled` and `idp.enabled` are set to `false`, all requests to the gateway controller are allowed without authentication. -### Authorization (Are you allowed?) -Gateway Controller routes are protected using **local roles** (for example `admin`, `developer`, `consumer`). +### Authorization (are you allowed?) +Gateway Controller routes are protected using **local roles** (for example, `admin`, `developer`, `consumer`). - If **`roles_claim` is NOT configured** in the IDP/JWT setup, **authorization is bypassed** for the Gateway Controller REST API routes (i.e., no role checks are performed). - If **`roles_claim` IS configured**, you **must** also configure **`role_mapping`**. Without a mapping, the controller cannot translate IDP roles → local roles, and requests will be denied. @@ -71,7 +71,7 @@ controller: consumer: ["*"] ``` -## Role Mapping Semantics +## Role mapping semantics `role_mapping` is defined as: ```text @@ -92,7 +92,7 @@ role_mapping: ``` In this example, a user in `platform-admins` becomes both `admin` and `developer` in the Gateway Controller. -## Troubleshooting (What you’ll observe) +## Troubleshooting (what you’ll observe) - **Requests are denied after enabling JWT auth**: verify `jwks_url` and (if set) `issuer` match the token you're sending. - **You enabled `roles_claim` and suddenly everything is forbidden**: add `role_mapping` (mapping is mandatory when `roles_claim` is provided). - **Users authenticate but don't have expected access**: confirm the token actually contains the configured `roles_claim`, and that its values match what you listed in `role_mapping`. diff --git a/en/docs/ai-gateway/analytics/analytics-header-filter.md b/en/docs/ai-gateway/analytics/analytics-header-filter.md index f312a639..30590a39 100644 --- a/en/docs/ai-gateway/analytics/analytics-header-filter.md +++ b/en/docs/ai-gateway/analytics/analytics-header-filter.md @@ -1,5 +1,5 @@ --- -title: "Analytics Header Filter" +title: "Analytics header filter" description: "Control which request and response headers are sent to analytics backends using allow or deny mode in API Platform AI Gateway." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/analytics/analytics-header-filter/ md_url: https://wso2.com/api-platform/docs/ai-gateway/analytics/analytics-header-filter.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# Analytics Header Filter +# Analytics header filter ## Overview @@ -21,19 +21,19 @@ The Analytics Header Filter policy allows you to control which request and respo The policy is only effective when analytics is enabled at the system level and must be explicitly added to the API’s policy chain. **Operation modes:** -- **"allow"**: Only the specified headers will be included in analytics (whitelist mode) -- **"deny"**: All headers except the specified ones will be included in analytics (blacklist mode) +- **"allow"**: Only the specified headers will be included in analytics (whitelist mode). +- **"deny"**: All headers except the specified ones will be included in analytics (blacklist mode). Request and response headers can have different operation modes, allowing for flexible filtering strategies. ## Features -* Filters request and response headers from analytics data collection using allow or deny modes -* Case-insensitive header matching -* Supports independent configuration with flexible filtering strategies with whitelist (allow) and blacklist (deny) modes -* Operates transparently without affecting request or response processing -* Helps protect sensitive information from being exposed in analytics systems +* Filters request and response headers from analytics data collection using allow or deny modes. +* Case-insensitive header matching. +* Supports independent configuration with flexible filtering strategies with whitelist (allow) and blacklist (deny) modes. +* Operates transparently without affecting request or response processing. +* Helps protect sensitive information from being exposed in analytics systems. ## Configuration @@ -45,7 +45,7 @@ Request and response headers can have different operation modes, allowing for fl | `requestHeadersToFilter` | object | No | - | Configuration for filtering request headers. Contains `operation` and `headers` properties. | | `responseHeadersToFilter` | object | No | - | Configuration for filtering response headers. Contains `operation` and `headers` properties. | -### Parameter Structure +### Parameter structure Each filter parameter (`requestHeadersToFilter` and `responseHeadersToFilter`) is an object with the following properties: @@ -57,16 +57,16 @@ Each filter parameter (`requestHeadersToFilter` and `responseHeadersToFilter`) i > **Note**: This policy only affects analytics data collection. It does not remove or modify headers sent to upstream services or returned to clients. -## System Requirements +## System requirements -* Analytics must be enabled globally via `config.yaml` (`analytics.enabled: true`) -* The policy must be explicitly applied to the API policy chain -* If analytics is disabled at the system level, this policy has no effect +* Analytics must be enabled globally via `config.yaml` (`analytics.enabled: true`). +* The policy must be explicitly applied to the API policy chain. +* If analytics is disabled at the system level, this policy has no effect. -## API Definition Example +## API definition example -The following example demonstrates how to apply the Analytics Header Filter policy to a LlmProvider: +The following example demonstrates how to apply the Analytics Header Filter policy to an `LlmProvider`: ```bash curl -X POST http://localhost:9090/llm-providers \ @@ -112,22 +112,22 @@ spec: EOF ``` -## Use Cases +## Use cases -- **Sensitive Data Protection**: Prevent authentication tokens, internal identifiers, or security-related headers from being sent to analytics systems. +- **Sensitive data protection**: Prevent authentication tokens, internal identifiers, or security-related headers from being sent to analytics systems. -- **Noise Reduction**: Exclude verbose or low-value headers to improve the clarity and usefulness of analytics data. +- **Noise reduction**: Exclude verbose or low-value headers to improve the clarity and usefulness of analytics data. -- **Compliance and Governance**: Support compliance requirements by ensuring certain headers are never exported outside the platform. +- **Compliance and governance**: Support compliance requirements by ensuring certain headers are never exported outside the platform. -- **Cost and Storage Optimization**: Reduce analytics payload size by removing unnecessary headers from published events. +- **Cost and storage optimization**: Reduce analytics payload size by removing unnecessary headers from published events. ## Notes * Header name matching is case-insensitive. * The `operation` field is required and must be either `"allow"` or `"deny"`. -* The `headers` array is required but can be empty. When the array is empty, all original headers are included(if allowed explicitly) in analytics for both `"allow"` and `"deny"` modes (safe fallback behavior). +* The `headers` array is required but can be empty. When the array is empty, all original headers are included (if allowed explicitly) in analytics for both `"allow"` and `"deny"` modes (safe fallback behavior). * Request and response headers can use different operation modes independently. * This policy does not block requests or responses. * Filtering applies only to analytics collection, not to runtime request handling. diff --git a/en/docs/ai-gateway/analytics/moesif-analytics.md b/en/docs/ai-gateway/analytics/moesif-analytics.md index bff1d93c..30fe0995 100644 --- a/en/docs/ai-gateway/analytics/moesif-analytics.md +++ b/en/docs/ai-gateway/analytics/moesif-analytics.md @@ -1,5 +1,5 @@ --- -title: "Moesif Analytics" +title: "Moesif analytics" description: "Configure Moesif in API Platform AI Gateway to capture and publish API request and response data." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/analytics/moesif-analytics/ md_url: https://wso2.com/api-platform/docs/ai-gateway/analytics/moesif-analytics.md @@ -33,11 +33,11 @@ This capability allows platform administrators and business stakeholders to gain ## Prerequisites - - Active Moesif Account and an Application ID + - Active Moesif account and an application ID > **Note:** For obtaining the Application ID: > - Step 1: Sign up in [Moesif](https://www.moesif.com/) -> - Sept 2: Follow the onboarding wizard. -> - Sept 3: During the sign up process, you will receive a Collector Application ID for your configured application. Copy this value and keep it saved. +> - Step 2: Follow the onboarding wizard. +> - Step 3: During the sign-up process, you will receive a Collector Application ID for your configured application. Copy this value and keep it saved. > For more detailed instructions and advanced configuration options, refer to the [official Moesif Documentation](https://www.moesif.com/docs). @@ -46,7 +46,7 @@ This capability allows platform administrators and business stakeholders to gain Analytics is configured entirely through the gateway `config.toml` file and is enabled at a system level. -### System Parameters (`config.toml`) +### System parameters (`config.toml`) #### Analytics @@ -58,21 +58,21 @@ Analytics is configured entirely through the gateway `config.toml` file and is e | Parameter | Type | Required | Description | | ---------------------- | ------- | -------- | ----------------------------------------- | -| `type` | string | Yes | Analytics publisher type (Currently limited only to ```moesif``` ) | +| `type` | string | Yes | Analytics publisher type (currently limited only to ```moesif``` ) | | `enabled` | boolean | Yes | Enables the publisher | -| `settings` | object | Yes | Map of Publisher specific attributes required for configuring the publisher client | +| `settings` | object | Yes | Map of publisher-specific attributes required for configuring the publisher client | -#### gRPC Event Server +#### gRPC event server This section configures both the Envoy access log streaming settings and the ALS (Access Log Service) server that receives those logs. The ALS server runs within the policy-engine component. | Parameter | Type | Required | Default | Description | | ----------------------- | -------- | -------- |---- | -------------------------------- | -| `buffer_flush_interval` | duration | No | `1000000000`| Maximum time Envoy waits(in nanoseconds) before flushing buffered access log entries.| +| `buffer_flush_interval` | duration | No | `1000000000`| Maximum time Envoy waits (in nanoseconds) before flushing buffered access log entries.| | `buffer_size_bytes` | int | No | `16384` | Maximum size of the in-memory buffer used to batch access log entries before sending them to ALS server. | -| `grpc_request_timeout` | duration | No | `20000000000` | Timeout duration Envoy waits(in nanoseconds) for a response from the ALS server before considering the log delivery attempt failed. | +| `grpc_request_timeout` | duration | No | `20000000000` | Timeout duration Envoy waits (in nanoseconds) for a response from the ALS server before considering the log delivery attempt failed. | | `server_port` | int | Yes | - | gRPC port on which the ALS server listens for incoming access log streams from Envoy. | -| `shutdown_timeout` | int | No | `600` | Maximum time allowed for the ALS server to gracefully shut down while completing in-flight log processing(in seconds). | +| `shutdown_timeout` | int | No | `600` | Maximum time allowed for the ALS server to gracefully shut down while completing in-flight log processing (in seconds). | | `als_plain_text` | boolean | No | `true` | Use plaintext gRPC | | `public_key_path` | string | No | - | Path to the public key used for securing ALS communication when transport-level encryption or authentication is enabled. | | `private_key_path` | string | No | - | Path to the private key used for securing ALS communication when transport-level encryption or authentication is enabled. | @@ -82,9 +82,9 @@ This section configures both the Envoy access log streaming settings and the ALS **Note:** The hostname for the ALS connection is automatically derived from the policy-engine configuration. The internal log name identifier is set to `"envoy_access_log"` and is not configurable. -## Configuration Examples +## Configuration examples -#### Integrate Moesif Publisher +#### Integrate Moesif publisher For Moesif analytics integration, the following publisher-specific attributes must be configured under the `settings` section. These parameters control authentication, batching behavior, and publish intervals for efficient analytics delivery. The required attributes are as follows. @@ -124,11 +124,11 @@ max_header_limit = 8192 ``` -## Use Cases +## Use cases -* **API Usage Visibility** – Understand how APIs are consumed across tenants and applications. -* **Operational Insights** – Observe traffic volume, response behavior, and latency trends. -* **Business Intelligence** – Support product and business decisions using API analytics data. -* **Platform Monitoring** – Gain observability into API behavior without impacting performance. +* **API usage visibility** – Understand how APIs are consumed across tenants and applications. +* **Operational insights** – Observe traffic volume, response behavior, and latency trends. +* **Business intelligence** – Support product and business decisions using API analytics data. +* **Platform monitoring** – Gain observability into API behavior without impacting performance. diff --git a/en/docs/ai-gateway/deployment-modes/immutable-gateway.md b/en/docs/ai-gateway/deployment-modes/immutable-gateway.md index 2246ae97..b4d90e91 100644 --- a/en/docs/ai-gateway/deployment-modes/immutable-gateway.md +++ b/en/docs/ai-gateway/deployment-modes/immutable-gateway.md @@ -1,5 +1,5 @@ --- -title: "Immutable Gateway" +title: "Immutable gateway" description: "Run API Platform AI Gateway in immutable mode, loading LLM and MCP configurations from files at startup for GitOps workflows." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/deployment-modes/immutable-gateway/ md_url: https://wso2.com/api-platform/docs/ai-gateway/deployment-modes/immutable-gateway.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "how-to" --- -# Immutable Gateway +# Immutable gateway This guide explains how to run the API Platform Gateway in **immutable mode**, where API configurations are loaded from files at startup instead of being managed through the REST API. @@ -79,7 +79,7 @@ Artifact files support Go template expressions for injecting dynamic values. Tem Use `| redact` for sensitive values to hide them from config dumps. A `| default "value"` pipe is available for fallback values. See [Gateway Artifact Templating](../../api-gateway/setup/artifact-templating.md) for the full function reference. -### Sample: Reading List API +### Sample: Reading list API Save the following as `artifacts/reading-list-v1.yaml`: diff --git a/en/docs/ai-gateway/deployment-modes/kubernetes/gateway-operator.md b/en/docs/ai-gateway/deployment-modes/kubernetes/gateway-operator.md index 83dce7b6..fc1a55cf 100644 --- a/en/docs/ai-gateway/deployment-modes/kubernetes/gateway-operator.md +++ b/en/docs/ai-gateway/deployment-modes/kubernetes/gateway-operator.md @@ -1,5 +1,5 @@ --- -title: "Kubernetes Operator for API Platform Gateway" +title: "Kubernetes operator for API Platform gateway" description: "Deploy API Platform AI Gateway on Kubernetes using the Gateway Operator with platform CRDs or the Kubernetes Gateway API." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/deployment-modes/kubernetes/gateway-operator/ md_url: https://wso2.com/api-platform/docs/ai-gateway/deployment-modes/kubernetes/gateway-operator.md @@ -12,13 +12,13 @@ last_updated: 2026-06-16 content_type: "how-to" --- -# Kubernetes Operator for API Platform Gateway +# Kubernetes operator for API Platform gateway The WSO2 API Platform Gateway Operator enables native Kubernetes deployment using a GitOps-friendly, operator-based model. It manages the full lifecycle of API gateways and REST APIs. You can use **either** platform CRDs **or** the **Kubernetes Gateway API** on the same operator build. ## Overview -### Path A — Platform CRDs (`APIGateway` + `RestApi`) +### Path A — platform CRDs (`apigateway` + `restapi`) | CRD | Purpose | |-----|---------| @@ -27,7 +27,7 @@ The WSO2 API Platform Gateway Operator enables native Kubernetes deployment usin The operator watches these CRs, runs Helm for the gateway runtime, and deploys APIs through gateway-controller’s management REST API. -### Path B — Kubernetes Gateway API (`Gateway` + `HTTPRoute`) +### Path B — Kubernetes Gateway API (`Gateway` + `httproute`) | Resource | Purpose | |----------|---------| @@ -47,7 +47,7 @@ The operator watches these CRs, runs Helm for the gateway runtime, and deploys A ## Installation -### 1. Install Cert-Manager +### 1. Install Cert-manager The operator requires cert-manager for TLS certificate management: @@ -61,7 +61,7 @@ helm upgrade --install \ --debug --wait --timeout 10m ``` -### 2. Install Gateway Operator +### 2. Install gateway operator ```sh helm install my-gateway-operator oci://ghcr.io/wso2/api-platform/helm-charts/gateway-operator --version 0.6.0 @@ -145,7 +145,7 @@ kubectl apply -f https://raw.githubusercontent.com/wso2/api-platform/refs/heads/ kubectl get restapi -n default -o json | jq '.items[0].status' ``` -### Test API Endpoints +### Test API endpoints **`RestApi` / APIGateway-managed API** (example context `/test`, operation `GET /info`): @@ -228,7 +228,7 @@ spec: from: Same ``` -### 4. Sample backend (Deployment + Service) +### 4. Sample backend (deployment + service) ```yaml apiVersion: apps/v1 @@ -322,7 +322,7 @@ spec: weight: 1 ``` -### 6. Optional: second HTTPRoute (`hello-api-2`) +### 6. Optional: Second HTTPRoute (`hello-api-2`) ```yaml apiVersion: gateway.networking.k8s.io/v1 @@ -361,11 +361,11 @@ Verify: `kubectl get gateway,httproute -n gateway-api-demo`, wait for parent con Common annotations on `HTTPRoute` are copied into the **`api.yaml`** payload (for example **`gateway.api-platform.wso2.com/context`**, **`api-version`**, **`api-handle`**, **`display-name`**, **`project-id`**). If **`context`** is omitted or only whitespace, it defaults to **`/`**. If a rule **`match`** omits **`method`**, the operator emits all RestApi-supported verbs for that path: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. -### Mixed clusters (`RestApi` + `Gateway`) +### Mixed clusters (`restapi` + `gateway`) If you run **both** `APIGateway`-selected **`RestApi`** resources and **Gateway API** routes, keep the **`gateway.api-platform.wso2.com/api-selector`** annotation on the **`Gateway`** (as in the YAML above) so this gateway does not select `RestApi` CRs meant for another `APIGateway`. -### Test API Endpoints +### Test API endpoints **Kubernetes Gateway API** — HTTPRoute **`hello-api`** from [above](#5-httproute-hello-api): API **`context`** `/hello-context`, route match path prefix **`/hello`** (hits Envoy HTTPS on the forwarded router port): @@ -378,18 +378,18 @@ curl --request GET \ Use **`NS=gateway-api-demo`** in the port-forward snippet when testing that demo. The sample backend may respond with a short plain-text body (e.g. `hello from gateway api demo`) depending on chart and image version. -## Adding Backend Certificates +## Adding backend certificates For APIs connecting to backends with self-signed certificates: -### 1. Download the Certificate +### 1. Download the certificate ```sh curl -X GET "https://raw.githubusercontent.com/wso2/api-platform/refs/heads/main/gateway/resources/secure-backend/test-backend-certs/test-backend.crt" \ -o /tmp/test-backend.crt ``` -### 2. Add Certificate to Gateway +### 2. Add certificate to gateway ```sh cert_path="/tmp/test-backend.crt" @@ -398,7 +398,7 @@ curl -X POST http://localhost:9090/api/management/v0.9/certificates -u "admin:ad -d "{\"certificate\":$(jq -Rs . < $cert_path),\"filename\":\"my-cert.pem\", \"name\":\"test\"}" ``` -## Custom Configuration +## Custom configuration Per-gateway Helm values are supplied as a **ConfigMap** whose data includes **`values.yaml`** (partial YAML is fine; the operator **deep-merges** it onto the operator’s default gateway values file loaded from **`gateway.helm.valuesFilePath`**). @@ -474,7 +474,7 @@ The operator reads **`metadata.annotations[gateway.api-platform.wso2.com/helm-va - **CRD path:** `APIGateway` drives Helm; `RestApi` drives management REST deploys. - **Gateway API path:** `Gateway` drives the same Helm install pattern; `HTTPRoute` is translated to the same management REST payload shape as `RestApi`. -## Default Ports +## Default ports | Port | Component | Description | |------|-----------|-------------| diff --git a/en/docs/ai-gateway/deployment-modes/kubernetes/kubernetes-standalone.md b/en/docs/ai-gateway/deployment-modes/kubernetes/kubernetes-standalone.md index 90130caa..10c92fc1 100644 --- a/en/docs/ai-gateway/deployment-modes/kubernetes/kubernetes-standalone.md +++ b/en/docs/ai-gateway/deployment-modes/kubernetes/kubernetes-standalone.md @@ -1,5 +1,5 @@ --- -title: "Kubernetes Standalone Mode" +title: "Kubernetes standalone mode — API Platform Gateway" description: "Install and manage API Platform AI Gateway on Kubernetes using the standalone Helm chart without the Gateway Operator." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/deployment-modes/kubernetes/kubernetes-standalone/ md_url: https://wso2.com/api-platform/docs/ai-gateway/deployment-modes/kubernetes/kubernetes-standalone.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "how-to" --- -# API Platform Gateway - Kubernetes Standalone Mode +# API Platform gateway - Kubernetes standalone mode This guide explains how to run API Platform Gateway in **Standalone Mode** using the gateway Helm chart only (without the Gateway Operator). @@ -24,7 +24,7 @@ Standalone mode is recommended when you want: For mode selection and architecture context, see [API Platform Kubernetes Gateway deployment modes](./overview.md). -## What Gets Deployed +## What gets deployed The gateway chart deploys the runtime components used by API Platform Gateway (controller and gateway runtime workloads) from chart templates and values. @@ -58,7 +58,7 @@ Verify: kubectl get pods -n cert-manager ``` -## Install Gateway Chart +## Install gateway chart Use one of the following patterns. @@ -85,7 +85,7 @@ helm install ap-gateway oci://ghcr.io/wso2/api-platform/helm-charts/gateway \ helm install ap-gateway oci://ghcr.io/wso2/api-platform/helm-charts/gateway \ --set gateway.controller.controlPlane.host="platform.example.com" \ --set gateway.controller.controlPlane.port=8443 \ - --set gateway.controller.controlPlane.token.value="your-token-here" \ + --set gateway.controller.controlPlane.token.value="" \ --set gateway.developmentMode=true ``` @@ -96,7 +96,7 @@ helm install ap-gateway oci://ghcr.io/wso2/api-platform/helm-charts/gateway \ -f custom-values.yaml ``` -## Verify Installation +## Verify installation ```bash helm status ap-gateway @@ -113,7 +113,7 @@ kubectl logs -l app.kubernetes.io/component=controller kubectl logs -l app.kubernetes.io/component=gateway-runtime ``` -## Upgrade and Uninstall +## Upgrade and uninstall Upgrade: @@ -133,7 +133,7 @@ Namespace-scoped uninstall: helm uninstall ap-gateway --namespace api-gateway ``` -## Core Configuration Areas +## Core configuration areas Most runtime configuration is controlled in `values.yaml`. Common sections: @@ -148,9 +148,9 @@ Most runtime configuration is controlled in `values.yaml`. Common sections: Refer to inline comments in chart `values.yaml` for all supported fields. -## TLS Configuration +## TLS configuration -### Option 1: cert-manager (recommended) +### Option 1: Cert-manager (recommended) ```bash helm install ap-gateway oci://ghcr.io/wso2/api-platform/helm-charts/gateway \ @@ -189,7 +189,7 @@ helm install ap-gateway oci://ghcr.io/wso2/api-platform/helm-charts/gateway \ --set gateway.controller.tls.secret.name=gateway-tls ``` -## Upstream Custom CAs +## Upstream custom CAs When calling upstream services that use private/self-signed CAs: @@ -203,9 +203,9 @@ helm install ap-gateway oci://ghcr.io/wso2/api-platform/helm-charts/gateway \ --set gateway.controller.upstreamCerts.secretName=upstream-ca-certs ``` -## Create and Invoke API +## Create and invoke API -### Port-forward Gateway Controller Service +### Port-forward gateway controller service ```bash kubectl port-forward svc/ap-gateway-controller 9090:9090 @@ -266,7 +266,7 @@ curl http://localhost:8080/reading-list/v1.0/books curl -k https://localhost:8443/reading-list/v1.0/books ``` -## Next Steps +## Next steps - For operator-managed lifecycle and CRDs, see [Kubernetes Operator deployment mode](./gateway-operator.md). - For mode comparison and migration context from Kubernetes Gateway 1.3.0, see the [deployment modes overview page](./overview.md). \ No newline at end of file diff --git a/en/docs/ai-gateway/deployment-modes/kubernetes/overview.md b/en/docs/ai-gateway/deployment-modes/kubernetes/overview.md index 417914c9..8ce5756c 100644 --- a/en/docs/ai-gateway/deployment-modes/kubernetes/overview.md +++ b/en/docs/ai-gateway/deployment-modes/kubernetes/overview.md @@ -1,5 +1,5 @@ --- -title: "AI Gateway Kubernetes Deployment Modes" +title: "AI Gateway Kubernetes deployment modes" description: "Choose between standalone and operator-managed Kubernetes deployment modes for API Platform AI Gateway." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/deployment-modes/kubernetes/overview/ md_url: https://wso2.com/api-platform/docs/ai-gateway/deployment-modes/kubernetes/overview.md @@ -12,28 +12,28 @@ last_updated: 2026-06-19 content_type: "overview" --- -# API Platform Kubernetes Gateway (V2.0.0) +# API Platform Kubernetes Gateway (v2.0.0) -API Platform Gateway is the latest evolution of the WSO2 Kubernetes gateway(APK) experience. +API Platform Gateway is the latest evolution of the WSO2 Kubernetes Gateway (APK) experience. If you are coming from WSO2 Kubernetes Gateway `1.3.0`, treat this as the successor track with a broader API Platform integration model and improved Kubernetes-native workflows. - Previous generation (reference): [WSO2 APK 1.3.0 docs](https://apk.docs.wso2.com/en/latest/) -- Current generation: API Platform Kubernetes Gateway V2.0.0 (this documentation set) +- Current generation: API Platform Kubernetes Gateway v2.0.0 (this documentation set) -## What Is New in V2.0.0 +## What is new in v2.0.0 -- Unified API Platform gateway model for both standalone and operator-driven deployments. +- Unified API Platform Gateway model for both standalone and operator-driven deployments. - Native support for Kubernetes Operator workflows and GitOps-style resource management. - Flexible API exposure model: - API Platform CRDs (`APIGateway`, `RestApi`, and related CRDs) - Kubernetes Gateway API (`GatewayClass`, `Gateway`, `HTTPRoute`, optional `APIPolicy`) - Improved extensibility for policies and secret/config-based parameter references. -## Deployment Modes +## Deployment modes Choose one of the following modes based on your operational model. -### 1) Kubernetes Standalone Mode +### 1) Kubernetes standalone mode Use this mode when you only need the gateway runtime and manage it directly via the gateway Helm chart. @@ -41,7 +41,7 @@ Use this mode when you only need the gateway runtime and manage it directly via - Best for simpler setups or environments where operator lifecycle management is not required. - Guide: [`kubernetes-standalone.md`](./kubernetes-standalone.md) -### 2) Kubernetes Operator Mode +### 2) Kubernetes operator mode Use this mode when you want operator-managed lifecycle, declarative resources, and automation. @@ -51,19 +51,19 @@ Use this mode when you want operator-managed lifecycle, declarative resources, a - Kubernetes Gateway API path (`Gateway` + `HTTPRoute`) - Guide: [`gateway-operator.md`](./gateway-operator.md) -## How to Choose a Mode +## How to choose a mode -- Choose **Standalone Mode** if your priority is a lightweight gateway runtime install with Helm-managed values. -- Choose **Operator Mode** if your priority is Kubernetes-native reconciliation, GitOps workflows, multi-resource lifecycle automation, and CRD-based API management. +- Choose **standalone mode** if your priority is a lightweight gateway runtime install with Helm-managed values. +- Choose **operator mode** if your priority is Kubernetes-native reconciliation, GitOps workflows, multi-resource lifecycle automation, and CRD-based API management. -## Policy Configuration +## Policy configuration -API Platform Kubernetes Gateway V2.0.0 supports attaching policies to APIs deployed in either mode. Policies control request/response mediation, rate limiting, authentication, and other gateway behaviors. +API Platform Kubernetes Gateway v2.0.0 supports attaching policies to APIs deployed in either mode. Policies control request/response mediation, rate limiting, authentication, and other gateway behaviors. For a full reference on available policies and how to configure them, see [Policy Configuration Overview](https://wso2.com/api-platform/docs/api-gateway/policies/overview/). -## Next Steps +## Next steps Learn more about the deployment modes: - [Standalone mode](./kubernetes-standalone.md) diff --git a/en/docs/ai-gateway/llm-proxy/guardrails/aws-bedrock-guardrail.md b/en/docs/ai-gateway/llm-proxy/guardrails/aws-bedrock-guardrail.md index e5187212..9e6d57fd 100644 --- a/en/docs/ai-gateway/llm-proxy/guardrails/aws-bedrock-guardrail.md +++ b/en/docs/ai-gateway/llm-proxy/guardrails/aws-bedrock-guardrail.md @@ -1,5 +1,5 @@ --- -title: "AWS Bedrock Guardrail" +title: "AWS Bedrock guardrail" description: "Validate LLM request and response content against AWS Bedrock Guardrails for content filtering, topic detection, and PII masking." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/aws-bedrock-guardrail/ md_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/aws-bedrock-guardrail.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# AWS Bedrock Guardrail +# AWS Bedrock guardrail ## Overview @@ -37,7 +37,7 @@ The policy supports multiple authentication modes including AWS IAM role assumpt ### Parameters -#### Request Phase +#### Request phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -46,7 +46,7 @@ The policy supports multiple authentication modes including AWS IAM role assumpt | `passthroughOnError` | boolean | No | `false` | If `true`, allows requests to proceed if AWS Bedrock Guardrail API call fails. If `false`, blocks requests on API errors. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information from AWS Bedrock Guardrail in error responses. | -#### Response Phase +#### Response phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -54,9 +54,9 @@ The policy supports multiple authentication modes including AWS IAM role assumpt | `passthroughOnError` | boolean | No | `false` | If `true`, allows requests to proceed if AWS Bedrock Guardrail API call fails. If `false`, blocks requests on API errors. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information from AWS Bedrock Guardrail in error responses. | -### System Parameters (Required) +### System parameters (required) -These parameters are typically configured at the gateway level and automatically injected, or you can override those values from the params section in the api artifact definition file as well: +These parameters are typically configured at the gateway level and automatically injected, or you can override those values from the params section in the API artifact definition file: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| @@ -71,7 +71,7 @@ These parameters are typically configured at the gateway level and automatically | `awsRoleExternalID` | string | No | External ID for role assumption (optional, for cross-account access security). | -### Configuring System Parameters in config.toml +### Configuring system parameters in config.toml System parameters can be configured globally in the gateway's `config.toml` file. These values serve as defaults for all AWS Bedrock Guardrail policy instances and can be overridden per-policy in the API configuration if needed. @@ -81,7 +81,7 @@ Add the following configuration section to your `config.toml` file: ```toml awsbedrock_guardrail_region = "us-east-1" -awsbedrock_guardrail_id = "your-guardrail-id" +awsbedrock_guardrail_id = "" awsbedrock_guardrail_version = "DRAFT" awsbedrock_access_key_id = "" awsbedrock_secret_access_key = "" @@ -91,7 +91,7 @@ awsbedrock_role_region = "" awsbedrock_role_external_id = "" ``` -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and validate specific fields within JSON payloads. Common examples: @@ -103,15 +103,15 @@ The guardrail supports JSONPath expressions to extract and validate specific fie If `jsonPath` is empty or not specified, the entire payload is treated as a string and validated. -## PII Handling +## PII handling -### Masking Mode (redactPII: false) +### Masking mode (redactPII: false) When `redactPII` is `false`: - **Request phase**: PII entities are masked with placeholders like `EMAIL_0001`, `PHONE_0002`, etc. - Use this mode when you need PII to flow through the system but want it masked during processing -### Redaction Mode (redactPII: true) +### Redaction mode (redactPII: true) When `redactPII` is `true`: - PII entities are permanently replaced with `*****` @@ -120,7 +120,7 @@ When `redactPII` is `true`: ## Examples -### Example 1: Basic Guardrail with Static Credentials +### Example 1: Basic guardrail with static credentials Deploy an LLM provider with AWS Bedrock Guardrail validation: @@ -200,7 +200,7 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Example 2: PII Redaction Mode +### Example 2: PII redaction mode Configure to redact PII: @@ -220,23 +220,23 @@ policies: jsonPath: "$.choices[0].message.content" ``` -## Use Cases +## Use cases -1. **Content Safety**: Enforce enterprise content policies to prevent inappropriate or harmful content from being processed or returned. +1. **Content safety**: Enforce enterprise content policies to prevent inappropriate or harmful content from being processed or returned. 2. **Compliance**: Meet regulatory requirements (HIPAA, GDPR, etc.) by detecting and masking PII in LLM interactions. -3. **Topic Control**: Restrict LLM usage to approved topics only, preventing misuse or access to sensitive domains. +3. **Topic control**: Restrict LLM usage to approved topics only, preventing misuse or access to sensitive domains. -4. **Data Privacy**: Mask sensitive information during processing while maintaining the ability to restore it in responses when needed. +4. **Data privacy**: Mask sensitive information during processing while maintaining the ability to restore it in responses when needed. -5. **Prohibited Word Filtering**: Block content containing prohibited words, phrases, or patterns defined in your guardrail. +5. **Prohibited word filtering**: Block content containing prohibited words, phrases, or patterns defined in your guardrail. -6. **Multi-tenant Security**: Isolate content policies per tenant or application using different guardrail configurations. +6. **Multi-tenant security**: Isolate content policies per tenant or application using different guardrail configurations. -7. **Audit and Monitoring**: Use detailed assessment information to audit content violations and improve policies. +7. **Audit and monitoring**: Use detailed assessment information to audit content violations and improve policies. -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: diff --git a/en/docs/ai-gateway/llm-proxy/guardrails/azure-content-safety.md b/en/docs/ai-gateway/llm-proxy/guardrails/azure-content-safety.md index 3a2e12ee..29233130 100644 --- a/en/docs/ai-gateway/llm-proxy/guardrails/azure-content-safety.md +++ b/en/docs/ai-gateway/llm-proxy/guardrails/azure-content-safety.md @@ -35,7 +35,7 @@ The policy uses Azure Content Safety's text analysis API to evaluate content and ### Parameters -#### Request Phase +#### Request phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -47,7 +47,7 @@ The policy uses Azure Content Safety's text analysis API to evaluate content and | `selfHarmCategory` | integer | No | `-1` | Severity threshold for self-harm category (0-7). `-1` disables this category. Content with severity >= threshold will be blocked. | | `violenceCategory` | integer | No | `-1` | Severity threshold for violence category (0-7). `-1` disables this category. Content with severity >= threshold will be blocked. | -#### Response Phase +#### Response phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -59,16 +59,16 @@ The policy uses Azure Content Safety's text analysis API to evaluate content and | `selfHarmCategory` | integer | No | `-1` | Severity threshold for self-harm category (0-7). `-1` disables this category. Content with severity >= threshold will be blocked. | | `violenceCategory` | integer | No | `-1` | Severity threshold for violence category (0-7). `-1` disables this category. Content with severity >= threshold will be blocked. | -### System Parameters (Required) +### System parameters (required) -These parameters are typically configured at the gateway level and automatically injected, or you can override those values from the params section in the api artifact definition file as well: +These parameters are typically configured at the gateway level and automatically injected, or you can override those values from the params section in the API artifact definition file as well: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `azureContentSafetyEndpoint` | string | Yes | Azure Content Safety API endpoint URL (without trailing slash). Example: `https://your-resource.cognitiveservices.azure.com` | | `azureContentSafetyKey` | string | Yes | Azure Content Safety API subscription key for authentication. Found in Azure Portal under your Content Safety resource's "Keys and Endpoint" section. | -### Configuring System Parameters in config.toml +### Configuring system parameters in config.toml System parameters can be configured globally in the gateway's `config.toml` file. These values serve as defaults for all Azure Content Safety guardrail policy instances and can be overridden per-policy in the API configuration if needed. @@ -77,11 +77,11 @@ System parameters can be configured globally in the gateway's `config.toml` file Add the following configuration section to your `config.toml` file: ```toml -azurecontentsafety_endpoint = "https://your-resource.cognitiveservices.azure.com" +azurecontentsafety_endpoint = "https://.cognitiveservices.azure.com" azurecontentsafety_key = "" ``` -## Severity Levels +## Severity levels Azure Content Safety uses an 8-level severity scale (0-7): @@ -91,12 +91,12 @@ Azure Content Safety uses an 8-level severity scale (0-7): - **5-6**: High severity - Highly concerning content - **7**: Maximum severity - Most severe harmful content -**Threshold Configuration**: +**Threshold configuration**: - Set a threshold value (0-7) to block content at or above that severity level - Set to `-1` to disable monitoring for that category - Example: `hateCategory: 3` blocks content with hate severity >= 3 -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and validate specific fields within JSON payloads. Common examples: @@ -111,7 +111,7 @@ If `jsonPath` is empty or not specified, the entire payload is treated as a stri ## Examples -### Example 1: Basic Content Moderation +### Example 1: Basic content moderation Deploy an LLM provider with Azure Content Safety validation: @@ -198,7 +198,7 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Example 2: Strict Moderation with All Categories +### Example 2: Strict moderation with all categories Configure strict moderation thresholds: @@ -227,7 +227,7 @@ policies: showAssessment: true ``` -### Example 3: Selective Category Monitoring +### Example 3: Selective category monitoring Monitor only specific categories: @@ -247,7 +247,7 @@ policies: violenceCategory: -1 # Disabled ``` -### Example 4: Lenient Moderation +### Example 4: Lenient moderation Allow more content with higher thresholds: @@ -268,32 +268,32 @@ policies: passthroughOnError: true ``` -## Use Cases +## Use cases -1. **Content Safety**: Protect users from harmful, offensive, or inappropriate content in LLM interactions. +1. **Content safety**: Protect users from harmful, offensive, or inappropriate content in LLM interactions. -2. **Regulatory Compliance**: Meet content moderation requirements for regulated industries or geographies. +2. **Regulatory compliance**: Meet content moderation requirements for regulated industries or geographies. -3. **Brand Safety**: Ensure LLM responses align with brand values and don't generate problematic content. +3. **Brand safety**: Ensure LLM responses align with brand values and don't generate problematic content. -4. **User Protection**: Prevent exposure to self-harm content, especially important for mental health applications. +4. **User protection**: Prevent exposure to self-harm content, especially important for mental health applications. -5. **Community Guidelines**: Enforce community standards for user-generated content processed through LLMs. +5. **Community guidelines**: Enforce community standards for user-generated content processed through LLMs. -6. **Multi-tenant Applications**: Apply different moderation policies per tenant or application context. +6. **Multi-tenant applications**: Apply different moderation policies per tenant or application context. -7. **Gradual Rollout**: Start with lenient thresholds and tighten based on actual content patterns. +7. **Gradual rollout**: Start with lenient thresholds and tighten based on actual content patterns. -8. **Audit and Analytics**: Use detailed assessment information to analyze content patterns and refine policies. +8. **Audit and analytics**: Use detailed assessment information to analyze content patterns and refine policies. -## Severity Threshold Guidelines +## Severity threshold guidelines **Recommended thresholds by use case**: -- **Strict (Family-friendly applications)**: 1-2 across all categories -- **Moderate (General business applications)**: 3-4 across all categories -- **Lenient (Technical/professional contexts)**: 5-6 for most categories, disable non-applicable ones -- **Educational/Research**: 4-5 with selective category monitoring +- **Strict (family-friendly applications)**: 1-2 across all categories +- **Moderate (general business applications)**: 3-4 across all categories +- **Lenient (technical/professional contexts)**: 5-6 for most categories, disable non-applicable ones +- **Educational/research**: 4-5 with selective category monitoring **Category-specific considerations**: @@ -302,7 +302,7 @@ policies: - **Self-harm**: Often set lower (1-2) due to safety concerns - **Violence**: Depends on context (1-2 for general use, higher for educational/historical content) -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: diff --git a/en/docs/ai-gateway/llm-proxy/guardrails/content-length.md b/en/docs/ai-gateway/llm-proxy/guardrails/content-length.md index e0411db5..824cbe1b 100644 --- a/en/docs/ai-gateway/llm-proxy/guardrails/content-length.md +++ b/en/docs/ai-gateway/llm-proxy/guardrails/content-length.md @@ -1,5 +1,5 @@ --- -title: "Content Length Guardrail" +title: "Content length guardrail" description: "Enforce minimum and maximum byte length limits on LLM request and response payloads using the Content Length guardrail." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/content-length/ md_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/content-length.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# Content Length Guardrail +# Content length guardrail ## Overview @@ -30,7 +30,7 @@ The Content Length Guardrail validates the byte length of request or response bo ### Parameters -#### Request Phase +#### Request phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -40,7 +40,7 @@ The Content Length Guardrail validates the byte length of request or response bo | `invert` | boolean | No | `false` | If `true`, validation passes when content length is NOT within the min-max range. If `false`, validation passes when content length is within the range. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information in error responses. | -#### Response Phase +#### Response phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -50,7 +50,7 @@ The Content Length Guardrail validates the byte length of request or response bo | `invert` | boolean | No | `false` | If `true`, validation passes when content length is NOT within the min-max range. If `false`, validation passes when content length is within the range. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information in error responses. | -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and validate specific fields within JSON payloads. Common examples: @@ -63,7 +63,7 @@ If `jsonPath` is empty or not specified, the entire payload is treated as a stri ## Examples -### Example 1: Basic Content Length Validation +### Example 1: Basic content length validation Deploy an LLM provider that limits request payloads to between 100 bytes and 1MB: @@ -111,7 +111,7 @@ EOF **Test the guardrail:** -**Note**: Ensure that "openai" is mapped to the appropriate IP address (e.g., 127.0.0.1) in your `/etc/hosts` file, or remove the vhost from the llm provider configuration and use localhost to invoke. +**Note**: Ensure that "openai" is mapped to the appropriate IP address (e.g., 127.0.0.1) in your `/etc/hosts` file, or remove the vhost from the LLM provider configuration and use localhost to invoke. ```bash # Valid request (should pass) @@ -143,31 +143,31 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Additional Configuration Options +### Additional configuration options You can customize the guardrail behavior by modifying the `policies` section: -- **Request and Response Validation**: Configure both `request` and `response` parameters to validate byte lengths in both directions. Use `showAssessment: true` to include detailed assessment information in error responses. +- **Request and response validation**: Configure both `request` and `response` parameters to validate byte lengths in both directions. Use `showAssessment: true` to include detailed assessment information in error responses. -- **Inverted Logic**: Set `invert: true` to allow only content *outside* the specified byte range. This is useful for blocking content that falls within a prohibited size range. +- **Inverted logic**: Set `invert: true` to allow only content *outside* the specified byte range. This is useful for blocking content that falls within a prohibited size range. -- **Full Payload Validation**: Omit the `jsonPath` parameter to validate the entire request body without JSONPath extraction. +- **Full payload validation**: Omit the `jsonPath` parameter to validate the entire request body without JSONPath extraction. -- **Field-Specific Validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). +- **Field-specific validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). -## Use Cases +## Use cases -1. **Resource Protection**: Prevent excessively large payloads that could exhaust system resources or cause performance degradation. +1. **Resource protection**: Prevent excessively large payloads that could exhaust system resources or cause performance degradation. -2. **Network Optimization**: Control payload sizes to optimize network transfer times and reduce bandwidth costs. +2. **Network optimization**: Control payload sizes to optimize network transfer times and reduce bandwidth costs. -3. **Storage Management**: Limit content sizes to manage storage requirements effectively. +3. **Storage management**: Limit content sizes to manage storage requirements effectively. -4. **API Rate Limiting**: Enforce size constraints as part of rate limiting strategies. +4. **API rate limiting**: Enforce size constraints as part of rate limiting strategies. -5. **Quality Assurance**: Ensure responses meet minimum size requirements for completeness. +5. **Quality assurance**: Ensure responses meet minimum size requirements for completeness. -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: diff --git a/en/docs/ai-gateway/llm-proxy/guardrails/json-schema.md b/en/docs/ai-gateway/llm-proxy/guardrails/json-schema.md index a306e8da..55c7f36a 100644 --- a/en/docs/ai-gateway/llm-proxy/guardrails/json-schema.md +++ b/en/docs/ai-gateway/llm-proxy/guardrails/json-schema.md @@ -1,5 +1,5 @@ --- -title: "JSON Schema Guardrail" +title: "JSON schema guardrail" description: "Validate LLM request and response body content against a JSON Schema definition to enforce structured data formats." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/json-schema/ md_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/json-schema.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# JSON Schema Guardrail +# JSON schema guardrail ## Overview @@ -30,25 +30,25 @@ The JSON Schema Guardrail validates request or response body content against a J ### Parameters -#### Request Phase +#### Request phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `schema` | string | Yes | - | JSON Schema as a string (must be valid JSON). Supports all JSON Schema draft 7 features. | | `jsonPath` | string | No | `""` | JSONPath expression to extract a specific value from JSON payload for validation. If empty, validates the entire payload against the schema. | -| `invert` | boolean | No | `false` | If `true`, validation passes when schema validation FAILS. If `false`, validation passes when schema validation succeeds. | +| `invert` | boolean | No | `false` | If `true`, validation passes when schema validation fails. If `false`, validation passes when schema validation succeeds. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed validation error information in error responses. | -#### Response Phase +#### Response phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `schema` | string | Yes | - | JSON Schema as a string (must be valid JSON). Supports all JSON Schema draft 7 features. | | `jsonPath` | string | No | `""` | JSONPath expression to extract a specific value from JSON payload for validation. If empty, validates the entire payload against the schema. | -| `invert` | boolean | No | `false` | If `true`, validation passes when schema validation FAILS. If `false`, validation passes when schema validation succeeds. | +| `invert` | boolean | No | `false` | If `true`, validation passes when schema validation fails. If `false`, validation passes when schema validation succeeds. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed validation error information in error responses. | -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and validate specific fields within JSON payloads. Common examples: @@ -59,20 +59,20 @@ The guardrail supports JSONPath expressions to extract and validate specific fie If `jsonPath` is empty or not specified, the entire payload is validated against the schema. -## JSON Schema Features +## JSON Schema features The guardrail supports JSON Schema Draft 7, including: - **Types**: `string`, `number`, `integer`, `boolean`, `object`, `array`, `null` - **Properties**: Define object properties and their schemas -- **Required Fields**: Specify which properties are mandatory +- **Required fields**: Specify which properties are mandatory - **Constraints**: `minLength`, `maxLength`, `minimum`, `maximum`, `pattern`, `enum` -- **Nested Structures**: Complex nested objects and arrays -- **Conditional Logic**: `if`, `then`, `else`, `allOf`, `anyOf`, `oneOf`, `not` +- **Nested structures**: Complex nested objects and arrays +- **Conditional logic**: `if`, `then`, `else`, `allOf`, `anyOf`, `oneOf`, `not` ## Examples -### Example 1: Basic Object Validation +### Example 1: Basic object validation Deploy an LLM provider that validates that request contains a user object with required fields: @@ -128,7 +128,7 @@ EOF **Test the guardrail:** -**Note**: Ensure that "openai" is mapped to the appropriate IP address (e.g., 127.0.0.1) in your `/etc/hosts` file, or remove the vhost from the llm provider configuration and use localhost to invoke. +**Note**: Ensure that "openai" is mapped to the appropriate IP address (e.g., 127.0.0.1) in your `/etc/hosts` file, or remove the vhost from the LLM provider configuration and use localhost to invoke. ```bash # Valid request (should pass) @@ -163,23 +163,23 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Additional Configuration Options +### Additional configuration options You can customize the guardrail behavior by modifying the `policies` section: -- **Request and Response Validation**: Configure both `request` and `response` parameters to validate JSON schemas in both directions. Use `showAssessment: true` to include detailed validation error information in error responses. +- **Request and response validation**: Configure both `request` and `response` parameters to validate JSON schemas in both directions. Use `showAssessment: true` to include detailed validation error information in error responses. -- **Inverted Logic**: Set `invert: true` to allow only content that does *not* match the schema. This is useful for blocking requests that match specific schema patterns. +- **Inverted logic**: Set `invert: true` to allow only content that does *not* match the schema. This is useful for blocking requests that match specific schema patterns. -- **Full Payload Validation**: Omit the `jsonPath` parameter to validate the entire request body against the schema. +- **Full payload validation**: Omit the `jsonPath` parameter to validate the entire request body against the schema. -- **Field-Specific Validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0]"` for message objects or `"$.results"` for response arrays). +- **Field-specific validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0]"` for message objects or `"$.results"` for response arrays). -## Use Cases +## Use cases -1. **API Contract Enforcement**: Ensure requests and responses conform to API specifications. +1. **API contract enforcement**: Ensure requests and responses conform to API specifications. -2. **Data Quality**: Validate data structure and types before processing. +2. **Data quality**: Validate data structure and types before processing. 3. **Security**: Enforce required fields and prevent injection of unexpected data structures. @@ -187,7 +187,7 @@ You can customize the guardrail behavior by modifying the `policies` section: 5. **Compliance**: Enforce data formats required by regulatory standards. -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: diff --git a/en/docs/ai-gateway/llm-proxy/guardrails/pii-masking-regex.md b/en/docs/ai-gateway/llm-proxy/guardrails/pii-masking-regex.md index 95be17d0..95f91820 100644 --- a/en/docs/ai-gateway/llm-proxy/guardrails/pii-masking-regex.md +++ b/en/docs/ai-gateway/llm-proxy/guardrails/pii-masking-regex.md @@ -1,5 +1,5 @@ --- -title: "PII Masking Regex Guardrail" +title: "PII masking regex guardrail" description: "Mask or redact personally identifiable information from LLM request and response bodies using configurable regex patterns." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/pii-masking-regex/ md_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/pii-masking-regex.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# PII Masking Regex Guardrail +# PII masking regex guardrail ## Overview @@ -35,7 +35,7 @@ The PII Masking Regex Guardrail masks or redacts Personally Identifiable Informa | `jsonPath` | string | No | `""` | JSONPath expression to extract a specific value from JSON payload. If empty, processes the entire payload as a string. | | `redactPII` | boolean | No | `false` | If `true`, redacts PII by replacing with "*****" (permanent, cannot be restored). If `false`, masks PII with placeholders that can be restored in responses. | -### PII Entity Configuration +### PII entity configuration Each PII entity in the `piiEntities` array must contain: @@ -44,7 +44,7 @@ Each PII entity in the `piiEntities` array must contain: | `piiEntity` | string | Yes | Name/type of the PII entity (e.g., "EMAIL", "PHONE", "SSN", "CREDIT_CARD"). Must contain only uppercase letters and underscores (matches `^[A-Z_]+$`). | | `piiRegex` | string | Yes | Regular expression pattern to match the PII entity. Must be a valid Go regexp pattern. | -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and process specific fields within JSON payloads. Common examples: @@ -55,16 +55,16 @@ The guardrail supports JSONPath expressions to extract and process specific fiel If `jsonPath` is empty or not specified, the entire payload is processed as a string. -## PII Masking Modes +## PII masking modes -### Masking Mode (`redactPII: false`) +### Masking mode (`redactPII: false`) - PII is replaced with placeholders in the format `[ENTITY_TYPE_XXXX]` where XXXX is a 4-digit hexadecimal number (e.g., `[EMAIL_0000]`, `[EMAIL_0001]`, `[PHONE_000a]`) - Placeholders are automatically restored in responses to their original values - Original PII values are stored temporarily in request metadata for restoration - Recommended when you need to preserve data for downstream processing or response generation -### Redaction Mode (`redactPII: true`) +### Redaction mode (`redactPII: true`) - PII is permanently replaced with "*****" - Cannot be restored in responses @@ -73,7 +73,7 @@ If `jsonPath` is empty or not specified, the entire payload is processed as a st ## Examples -### Example 1: Basic PII Masking +### Example 1: Basic PII masking Deploy an LLM provider that masks email addresses and phone numbers in requests and restores them in responses: @@ -125,7 +125,7 @@ EOF **Test the guardrail:** -**Note**: Ensure that "openai" is mapped to the appropriate IP address (e.g., 127.0.0.1) in your `/etc/hosts` file, or remove the vhost from the llm provider configuration and use localhost to invoke. +**Note**: Ensure that "openai" is mapped to the appropriate IP address (e.g., 127.0.0.1) in your `/etc/hosts` file, or remove the vhost from the LLM provider configuration and use localhost to invoke. ```bash # Request with PII (should be masked) @@ -143,35 +143,35 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Additional Configuration Options +### Additional configuration options You can customize the guardrail behavior by modifying the `policies` section: -- **PII Redaction**: Set `redactPII: true` to permanently replace PII with "*****" (cannot be restored). Set `redactPII: false` to use masking mode with placeholders that can be restored in responses. +- **PII redaction**: Set `redactPII: true` to permanently replace PII with "*****" (cannot be restored). Set `redactPII: false` to use masking mode with placeholders that can be restored in responses. -- **Multiple PII Types**: Configure multiple `piiEntities` in the array to detect and mask/redact various PII types (e.g., EMAIL, PHONE, CREDIT_CARD, SSN, IP_ADDRESS, DATE_OF_BIRTH). +- **Multiple PII types**: Configure multiple `piiEntities` in the array to detect and mask/redact various PII types (e.g., EMAIL, PHONE, CREDIT_CARD, SSN, IP_ADDRESS, DATE_OF_BIRTH). -- **Full Payload Processing**: Omit the `jsonPath` parameter to process the entire request body without JSONPath extraction. +- **Full payload processing**: Omit the `jsonPath` parameter to process the entire request body without JSONPath extraction. -- **Field-Specific Processing**: Use `jsonPath` to extract and process PII from specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content). +- **Field-specific processing**: Use `jsonPath` to extract and process PII from specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content). -- **Response Restoration**: When using masking mode (`redactPII: false`), PII is automatically restored in responses. No separate response configuration is needed. If `redactPII: true`, no restoration occurs in the response phase. +- **Response restoration**: When using masking mode (`redactPII: false`), PII is automatically restored in responses. No separate response configuration is needed. If `redactPII: true`, no restoration occurs in the response phase. -## Use Cases +## Use cases -1. **Privacy Protection**: Mask or redact PII before sending data to AI services or external systems. +1. **Privacy protection**: Mask or redact PII before sending data to AI services or external systems. 2. **Compliance**: Meet regulatory requirements (GDPR, CCPA, HIPAA) for PII handling. -3. **Data Minimization**: Reduce exposure of sensitive data in logs, analytics, or third-party integrations. +3. **Data minimization**: Reduce exposure of sensitive data in logs, analytics, or third-party integrations. -4. **Secure Processing**: Allow AI processing while protecting user privacy through masking. +4. **Secure processing**: Allow AI processing while protecting user privacy through masking. -5. **Audit Trail**: Maintain masked versions of data for auditing while protecting original values. +5. **Audit trail**: Maintain masked versions of data for auditing while protecting original values. -## How It Works +## How it works -### Request Phase (Masking) +### Request phase (masking) 1. Extract content using JSONPath (if specified) or use entire payload 2. Apply each PII regex pattern to find matches @@ -179,7 +179,7 @@ You can customize the guardrail behavior by modifying the `policies` section: 4. Store mapping of placeholders to original values (for masking mode) 5. Forward masked content to upstream service -### Response Phase (Restoration) +### Response phase (restoration) 1. Check if PII was masked in the request phase (metadata contains PII mappings) 2. If `redactPII: false` and mappings exist, replace placeholders with original PII values @@ -187,7 +187,7 @@ You can customize the guardrail behavior by modifying the `policies` section: 4. Return restored content or original response -#### Sample Payload after intervention from Regex PII Masking with redact=true +#### Sample payload after intervention from regex PII masking with redact=true ``` { diff --git a/en/docs/ai-gateway/llm-proxy/guardrails/regex.md b/en/docs/ai-gateway/llm-proxy/guardrails/regex.md index 1cfebfb4..7dc79675 100644 --- a/en/docs/ai-gateway/llm-proxy/guardrails/regex.md +++ b/en/docs/ai-gateway/llm-proxy/guardrails/regex.md @@ -1,5 +1,5 @@ --- -title: "Regex Guardrail" +title: "Regex guardrail" description: "Validate LLM request and response content against regular expression patterns to enforce formats or detect prohibited content." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/regex/ md_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/regex.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# Regex Guardrail +# Regex guardrail ## Overview @@ -30,25 +30,25 @@ The Regex Guardrail validates request or response body content against regular e ### Parameters -#### Request Phase +#### Request phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `regex` | string | Yes | - | Regular expression pattern to match against the content. Must be at least 1 character. | | `jsonPath` | string | No | `""` | JSONPath expression to extract a specific value from JSON payload. If empty, validates the entire payload as a string. | -| `invert` | boolean | No | `false` | If `true`, validation passes when regex does NOT match. If `false`, validation passes when regex matches. | +| `invert` | boolean | No | `false` | If `true`, validation passes when regex does not match. If `false`, validation passes when regex matches. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information in error responses. | -#### Response Phase +#### Response phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `regex` | string | Yes | - | Regular expression pattern to match against the content. Must be at least 1 character. | | `jsonPath` | string | No | `""` | JSONPath expression to extract a specific value from JSON payload. If empty, validates the entire payload as a string. | -| `invert` | boolean | No | `false` | If `true`, validation passes when regex does NOT match. If `false`, validation passes when regex matches. | +| `invert` | boolean | No | `false` | If `true`, validation passes when regex does not match. If `false`, validation passes when regex matches. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information in error responses. | -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and validate specific fields within JSON payloads. Common examples: @@ -59,7 +59,7 @@ The guardrail supports JSONPath expressions to extract and validate specific fie If `jsonPath` is empty or not specified, the entire payload is treated as a string and validated. -## Regular Expression Syntax +## Regular expression syntax The guardrail uses Go's standard regexp package, which supports RE2 syntax. Key features: @@ -72,7 +72,7 @@ The guardrail uses Go's standard regexp package, which supports RE2 syntax. Key ## Examples -### Example 1: Email Validation +### Example 1: Email validation Deploy an LLM provider that protects against sensitive data leaks by blocking any payloads that mention the word "password" (case-insensitive) in either the user’s message or the LLM’s response. This is achieved by using the regex policy to validate both request and response payloads: @@ -121,7 +121,7 @@ EOF **Test the guardrail:** -**Note**: Ensure that "openai" is mapped to the appropriate IP address (e.g., 127.0.0.1) in your `/etc/hosts` file, or remove the vhost from the llm provider configuration and use localhost to invoke. +**Note**: Ensure that "openai" is mapped to the appropriate IP address (e.g., 127.0.0.1) in your `/etc/hosts` file, or remove the vhost from the LLM provider configuration and use localhost to invoke. ```bash # Valid request (should pass) @@ -153,31 +153,31 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Additional Configuration Options +### Additional configuration options You can customize the guardrail behavior by modifying the `policies` section: -- **Request and Response Validation**: Configure both `request` and `response` parameters to validate patterns in both directions. Use `showAssessment: true` to include detailed assessment information in error responses. +- **Request and response validation**: Configure both `request` and `response` parameters to validate patterns in both directions. Use `showAssessment: true` to include detailed assessment information in error responses. -- **Inverted Logic**: Set `invert: true` to allow only content that does *not* match the regex pattern. This is useful for blocking prohibited patterns (e.g., password-related content, admin keywords). +- **Inverted logic**: Set `invert: true` to allow only content that does *not* match the regex pattern. This is useful for blocking prohibited patterns (e.g., password-related content, admin keywords). -- **Full Payload Validation**: Omit the `jsonPath` parameter to validate the entire request body without JSONPath extraction. +- **Full payload validation**: Omit the `jsonPath` parameter to validate the entire request body without JSONPath extraction. -- **Field-Specific Validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). +- **Field-specific validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). -## Use Cases +## Use cases -1. **Format Validation**: Ensure user inputs match expected formats (emails, phone numbers, IDs). +1. **Format validation**: Ensure user inputs match expected formats (emails, phone numbers, IDs). -2. **Content Filtering**: Block or allow content based on pattern matching (prohibited words, sensitive patterns). +2. **Content filtering**: Block or allow content based on pattern matching (prohibited words, sensitive patterns). -3. **Security Enforcement**: Detect and block potentially malicious patterns or injection attempts. +3. **Security enforcement**: Detect and block potentially malicious patterns or injection attempts. -4. **Data Quality**: Ensure responses follow specific formatting requirements or contain required elements. +4. **Data quality**: Ensure responses follow specific formatting requirements or contain required elements. 5. **Compliance**: Enforce patterns required by regulatory standards or business rules. -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: diff --git a/en/docs/ai-gateway/llm-proxy/guardrails/semantic-prompt-guard.md b/en/docs/ai-gateway/llm-proxy/guardrails/semantic-prompt-guard.md index 97a51666..471e43ad 100644 --- a/en/docs/ai-gateway/llm-proxy/guardrails/semantic-prompt-guard.md +++ b/en/docs/ai-gateway/llm-proxy/guardrails/semantic-prompt-guard.md @@ -1,5 +1,5 @@ --- -title: "Semantic Prompt Guardrail" +title: "Semantic prompt guardrail" description: "Block semantically similar prompts using embedding-based similarity matching against configured allow and deny phrase lists." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/semantic-prompt-guard/ md_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/semantic-prompt-guard.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# Semantic Prompt Guardrail +# Semantic prompt guardrail ## Overview @@ -29,15 +29,15 @@ The policy uses embedding models (OpenAI, Mistral, or Azure OpenAI) to convert p - **JSONPath extraction**: Extract specific fields from request body for validation - **Detailed assessment information**: Optional detailed violation information in error responses -## How It Works +## How it works -1. **Text Extraction**: Extracts prompt text from the request body using JSONPath (if configured) or uses the entire request body -2. **Embedding Generation**: Generates a vector embedding from the extracted prompt using the configured embedding provider -3. **Validation Strategy**: The validation logic depends on which lists are configured: +1. **Text extraction**: Extracts prompt text from the request body using JSONPath (if configured) or uses the entire request body +2. **Embedding generation**: Generates a vector embedding from the extracted prompt using the configured embedding provider +3. **Validation strategy**: The validation logic depends on which lists are configured: - **Deny list only**: Compares prompt embedding against all denied phrases. If any denied phrase has similarity >= `denySimilarityThreshold`, the request is blocked. Otherwise, it proceeds. - **Allow list only**: Compares prompt embedding against all allowed phrases. If no allowed phrase has similarity >= `allowSimilarityThreshold`, the request is blocked. Otherwise, it proceeds. - **Both lists**: First checks the deny list (blocks if similarity >= `denySimilarityThreshold`), then checks the allow list (blocks if similarity < `allowSimilarityThreshold`). Request proceeds only if it passes both checks. -4. **Validation Result**: Request proceeds if validation passes, or is blocked with HTTP 422 if validation fails +4. **Validation result**: Request proceeds if validation passes, or is blocked with HTTP 422 if validation fails ## Configuration @@ -54,9 +54,9 @@ The policy uses embedding models (OpenAI, Mistral, or Azure OpenAI) to convert p \* At least one of `allowedPhrases` or `deniedPhrases` must be provided. -### System Parameters (Required) +### System parameters (required) -These parameters are typically configured at the gateway level and automatically injected, or you can override those values from the params section in the api artifact definition file as well: +These parameters are typically configured at the gateway level and automatically injected, or you can override those values from the params section in the API artifact definition file: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| @@ -65,7 +65,7 @@ These parameters are typically configured at the gateway level and automatically | `embeddingModel` | string | Conditional | - | Embedding model name. **Required for OPENAI and MISTRAL**, not required for AZURE_OPENAI (deployment name is in endpoint URL). Examples: OpenAI: `text-embedding-ada-002` or `text-embedding-3-small`, Mistral: `mistral-embed` | | `apiKey` | string | Yes | API key for the embedding service authentication | -### Configuring System Parameters in config.toml +### Configuring system parameters in config.toml System parameters can be configured globally in the gateway's `config.toml` file. These values serve as defaults for all Semantic Prompt Guard policy instances and can be overridden per-policy in the API configuration if needed. @@ -81,11 +81,11 @@ embedding_provider_dimension = 1024 embedding_provider_api_key = "" ``` -## Similarity Threshold Guidelines +## Similarity threshold guidelines The similarity thresholds control how similar prompts must be to trigger allow/deny decisions: -### Allow Similarity Threshold +### Allow similarity threshold - **0.95-1.0**: Very strict matching. Only near-identical prompts to allowed phrases will pass. Use for exact-match scenarios. - **0.85-0.94**: Recommended for most use cases. Catches semantically equivalent prompts with some wording variation. @@ -95,7 +95,7 @@ The similarity thresholds control how similar prompts must be to trigger allow/d **Recommendation**: Start with 0.65 and adjust based on your use case. Monitor false positives/negatives to fine-tune. -### Deny Similarity Threshold +### Deny similarity threshold - **0.95-1.0**: Very strict blocking. Only near-identical prompts to denied phrases will be blocked. - **0.85-0.94**: Recommended for most use cases. Catches semantically equivalent prompts with some wording variation. @@ -105,14 +105,14 @@ The similarity thresholds control how similar prompts must be to trigger allow/d **Recommendation**: Start with 0.65 and adjust based on your use case. Monitor false positives to fine-tune. -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract specific text from request bodies before validation. This is useful for: - Extracting message content from chat completion requests - Focusing on specific prompt fields while ignoring metadata - Handling structured JSON payloads -### Common JSONPath Examples +### Common JSONPath examples - `$.messages[0].content` - First message's content in chat completions - `$.messages[-1].content` - Last message's content @@ -122,7 +122,7 @@ The guardrail supports JSONPath expressions to extract specific text from reques ## Examples -### Example 1: Deny List Only - Blocking Prohibited Content +### Example 1: Deny list only - blocking prohibited content Deploy an LLM provider that blocks prompts similar to prohibited phrases: @@ -202,7 +202,7 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Example 2: Allow List Only - Whitelist Approach +### Example 2: Allow list only - whitelist approach Deploy an LLM provider that only allows prompts similar to approved phrases: @@ -248,7 +248,7 @@ spec: EOF ``` -### Example 3: Combined Allow and Deny Lists +### Example 3: Combined allow and deny lists Use both allow and deny lists for comprehensive filtering: @@ -274,7 +274,7 @@ policies: showAssessment: true ``` -### Example 4: Azure OpenAI with Custom Timeout +### Example 4: Azure OpenAI with custom timeout Configure semantic prompt guardrail with Azure OpenAI and extended timeout: @@ -293,25 +293,25 @@ policies: - "Another prohibited phrase" ``` -## Use Cases +## Use cases -1. **Content Safety**: Block prompts that are semantically similar to prohibited content, even when exact keywords differ. +1. **Content safety**: Block prompts that are semantically similar to prohibited content, even when exact keywords differ. -2. **Whitelist Filtering**: Only allow prompts that match approved use cases or topics, ensuring LLM usage stays within defined boundaries. +2. **Whitelist filtering**: Only allow prompts that match approved use cases or topics, ensuring LLM usage stays within defined boundaries. 3. **Compliance**: Enforce content policies by blocking prompts similar to non-compliant examples. -4. **Abuse Prevention**: Detect and block variations of known abuse patterns, even when attackers try to evade keyword filters. +4. **Abuse prevention**: Detect and block variations of known abuse patterns, even when attackers try to evade keyword filters. -5. **Domain Restriction**: Restrict LLM usage to specific domains by allowing only prompts similar to approved domain-specific phrases. +5. **Domain restriction**: Restrict LLM usage to specific domains by allowing only prompts similar to approved domain-specific phrases. -6. **Multi-tenant Security**: Apply different allow/deny lists per tenant or application to enforce tenant-specific content policies. +6. **Multi-tenant security**: Apply different allow/deny lists per tenant or application to enforce tenant-specific content policies. -7. **Prompt Injection Prevention**: Block prompts that are semantically similar to known prompt injection attacks. +7. **Prompt injection prevention**: Block prompts that are semantically similar to known prompt injection attacks. -8. **Quality Control**: Ensure prompts match expected patterns for better response quality and consistency. +8. **Quality control**: Ensure prompts match expected patterns for better response quality and consistency. -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: @@ -371,15 +371,15 @@ For errors during processing (e.g., JSONPath extraction failures, embedding gene } ``` -## Performance Considerations +## Performance considerations -1. **Embedding Generation Latency**: Generating embeddings adds ~100-500ms to request processing. This is a one-time cost per request. +1. **Embedding generation latency**: Generating embeddings adds ~100-500ms to request processing. This is a one-time cost per request. -2. **Batch Processing**: All allow/deny phrase embeddings are generated in a single batch during policy initialization, minimizing initialization overhead. +2. **Batch processing**: All allow/deny phrase embeddings are generated in a single batch during policy initialization, minimizing initialization overhead. -3. **Similarity Calculation**: Cosine similarity calculations are fast (typically < 10ms) even with many phrases. +3. **Similarity calculation**: Cosine similarity calculations are fast (typically < 10ms) even with many phrases. -4. **Embedding Provider Selection**: +4. **Embedding provider selection**: - OpenAI: Fast, reliable, good for most use cases - Mistral: Alternative option with good performance - Azure OpenAI: Good for Azure-integrated environments diff --git a/en/docs/ai-gateway/llm-proxy/guardrails/sentence-count.md b/en/docs/ai-gateway/llm-proxy/guardrails/sentence-count.md index 1ac4f599..e5a7490e 100644 --- a/en/docs/ai-gateway/llm-proxy/guardrails/sentence-count.md +++ b/en/docs/ai-gateway/llm-proxy/guardrails/sentence-count.md @@ -1,5 +1,5 @@ --- -title: "Sentence Count Guardrail" +title: "Sentence count guardrail" description: "Enforce minimum and maximum sentence count limits on LLM request and response content using the Sentence Count guardrail." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/sentence-count/ md_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/sentence-count.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# Sentence Count Guardrail +# Sentence count guardrail ## Overview @@ -30,27 +30,27 @@ The Sentence Count Guardrail validates the sentence count of request or response ### Parameters -#### Request Phase +#### Request phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `min` | integer | Yes | - | Minimum allowed sentence count (inclusive). Must be >= 0. | | `max` | integer | Yes | - | Maximum allowed sentence count (inclusive). Must be >= 1. | | `jsonPath` | string | No | `""` | JSONPath expression to extract a specific value from JSON payload. If empty, validates the entire payload as a string. | -| `invert` | boolean | No | `false` | If `true`, validation passes when sentence count is NOT within the min-max range. If `false`, validation passes when sentence count is within the range. | +| `invert` | boolean | No | `false` | If `true`, validation passes when sentence count is not within the min-max range. If `false`, validation passes when sentence count is within the range. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information in error responses. | -#### Response Phase +#### Response phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `min` | integer | Yes | - | Minimum allowed sentence count (inclusive). Must be >= 0. | | `max` | integer | Yes | - | Maximum allowed sentence count (inclusive). Must be >= 1. | | `jsonPath` | string | No | `""` | JSONPath expression to extract a specific value from JSON payload. If empty, validates the entire payload as a string. | -| `invert` | boolean | No | `false` | If `true`, validation passes when sentence count is NOT within the min-max range. If `false`, validation passes when sentence count is within the range. | +| `invert` | boolean | No | `false` | If `true`, validation passes when sentence count is not within the min-max range. If `false`, validation passes when sentence count is within the range. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information in error responses. | -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and validate specific fields within JSON payloads. Common examples: @@ -61,7 +61,7 @@ The guardrail supports JSONPath expressions to extract and validate specific fie If `jsonPath` is empty or not specified, the entire payload is treated as a string and validated. -## Sentence Detection +## Sentence detection Sentences are detected based on standard sentence-ending punctuation marks: - Period (.) @@ -72,7 +72,7 @@ The guardrail counts sequences of characters ending with these punctuation marks ## Examples -### Example 1: Basic Sentence Count Validation +### Example 1: Basic sentence count validation Deploy an LLM provider that ensures requests contain between 1 and 10 sentences: @@ -121,7 +121,7 @@ EOF **Test the guardrail:** -**Note**: Ensure that "openai" is mapped to the appropriate IP address (e.g., 127.0.0.1) in your `/etc/hosts` file, or remove the vhost from the llm provider configuration and use localhost to invoke. +**Note**: Ensure that "openai" is mapped to the appropriate IP address (e.g., 127.0.0.1) in your `/etc/hosts` file, or remove the vhost from the LLM provider configuration and use localhost to invoke. ```bash # Valid request (should pass) @@ -153,31 +153,31 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Additional Configuration Options +### Additional configuration options You can customize the guardrail behavior by modifying the `policies` section: -- **Request and Response Validation**: Configure both `request` and `response` parameters to validate sentence counts in both directions. Use `showAssessment: true` to include detailed assessment information in error responses. +- **Request and response validation**: Configure both `request` and `response` parameters to validate sentence counts in both directions. Use `showAssessment: true` to include detailed assessment information in error responses. -- **Inverted Logic**: Set `invert: true` to allow only content *outside* the specified sentence range. This is useful for blocking content that falls within a prohibited sentence count range. +- **Inverted logic**: Set `invert: true` to allow only content *outside* the specified sentence range. This is useful for blocking content that falls within a prohibited sentence count range. -- **Full Payload Validation**: Omit the `jsonPath` parameter to validate the entire request body without JSONPath extraction. +- **Full payload validation**: Omit the `jsonPath` parameter to validate the entire request body without JSONPath extraction. -- **Field-Specific Validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). +- **Field-specific validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). -## Use Cases +## Use cases -1. **Content Quality Assurance**: Ensure responses meet minimum sentence requirements for completeness and clarity. +1. **Content quality assurance**: Ensure responses meet minimum sentence requirements for completeness and clarity. -2. **Response Length Control**: Limit verbosity to maintain concise communication standards. +2. **Response length control**: Limit verbosity to maintain concise communication standards. -3. **Input Validation**: Ensure user prompts contain sufficient context (minimum sentences) without being excessive. +3. **Input validation**: Ensure user prompts contain sufficient context (minimum sentences) without being excessive. -4. **Consistency Enforcement**: Maintain consistent response formats across different AI interactions. +4. **Consistency enforcement**: Maintain consistent response formats across different AI interactions. -5. **Cost Management**: Control response length to manage token usage and associated costs. +5. **Cost management**: Control response length to manage token usage and associated costs. -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: diff --git a/en/docs/ai-gateway/llm-proxy/guardrails/url.md b/en/docs/ai-gateway/llm-proxy/guardrails/url.md index 3cb7bbf8..94ecc346 100644 --- a/en/docs/ai-gateway/llm-proxy/guardrails/url.md +++ b/en/docs/ai-gateway/llm-proxy/guardrails/url.md @@ -1,5 +1,5 @@ --- -title: "URL Guardrail" +title: "URL guardrail" description: "Validate URLs found in LLM request and response content by checking reachability through DNS resolution or HTTP HEAD requests." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/url/ md_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/url.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# URL Guardrail +# URL guardrail ## Overview @@ -30,7 +30,7 @@ The URL Guardrail validates URLs found in request or response body content by ch ### Parameters -#### Request Phase +#### Request phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -39,7 +39,7 @@ The URL Guardrail validates URLs found in request or response body content by ch | `timeout` | integer | No | `3000` | Timeout in milliseconds for DNS lookup or HTTP HEAD request. Default is 3000ms (3 seconds). | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information including invalid URLs in error responses. | -#### Response Phase +#### Response phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -48,7 +48,7 @@ The URL Guardrail validates URLs found in request or response body content by ch | `timeout` | integer | No | `3000` | Timeout in milliseconds for DNS lookup or HTTP HEAD request. Default is 3000ms (3 seconds). | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information including invalid URLs in error responses. | -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and validate specific fields within JSON payloads. Common examples: @@ -59,9 +59,9 @@ The guardrail supports JSONPath expressions to extract and validate specific fie If `jsonPath` is empty or not specified, the entire payload is treated as a string and validated. -## URL Validation Modes +## URL validation modes -### DNS-Only Validation (`onlyDNS: true`) +### DNS-only validation (`onlyDNS: true`) - Faster validation method - Only checks if the domain name resolves via DNS @@ -69,7 +69,7 @@ If `jsonPath` is empty or not specified, the entire payload is treated as a stri - Less reliable for detecting broken links - Suitable for quick validation when HTTP checks are not necessary -### HTTP HEAD Request Validation (`onlyDNS: false`) +### HTTP HEAD request validation (`onlyDNS: false`) - More thorough validation method - Performs DNS lookup and HTTP HEAD request @@ -80,7 +80,7 @@ If `jsonPath` is empty or not specified, the entire payload is treated as a stri ## Examples -### Example 1: Basic URL Validation +### Example 1: Basic URL validation Deploy an LLM provider that validates URLs in request content using HTTP HEAD requests: @@ -129,7 +129,7 @@ EOF **Test the guardrail:** -**Note**: Ensure that "openai" is mapped to the appropriate IP address (e.g., 127.0.0.1) in your `/etc/hosts` file, or remove the vhost from the llm provider configuration and use localhost to invoke. +**Note**: Ensure that "openai" is mapped to the appropriate IP address (e.g., 127.0.0.1) in your `/etc/hosts` file, or remove the vhost from the LLM provider configuration and use localhost to invoke. ```bash # Valid request (should pass) @@ -161,35 +161,35 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Additional Configuration Options +### Additional configuration options You can customize the guardrail behavior by modifying the `policies` section: -- **Request and Response Validation**: Configure both `request` and `response` parameters to validate URLs in both directions. Use `showAssessment: true` to include detailed assessment information including invalid URLs in error responses. +- **Request and response validation**: Configure both `request` and `response` parameters to validate URLs in both directions. Use `showAssessment: true` to include detailed assessment information including invalid URLs in error responses. -- **DNS-Only Validation**: Set `onlyDNS: true` for faster validation that only checks DNS resolution. This is less reliable but faster than HTTP HEAD validation. +- **DNS-only validation**: Set `onlyDNS: true` for faster validation that only checks DNS resolution. This is less reliable but faster than HTTP HEAD validation. -- **HTTP HEAD Validation**: Set `onlyDNS: false` (default) for more thorough validation that performs both DNS lookup and HTTP HEAD request to verify URL reachability. +- **HTTP HEAD validation**: Set `onlyDNS: false` (default) for more thorough validation that performs both DNS lookup and HTTP HEAD request to verify URL reachability. -- **Timeout Configuration**: Adjust the `timeout` parameter (in milliseconds) based on network conditions and acceptable latency. Default is 3000ms (3 seconds). +- **Timeout configuration**: Adjust the `timeout` parameter (in milliseconds) based on network conditions and acceptable latency. Default is 3000ms (3 seconds). -- **Full Payload Validation**: Omit the `jsonPath` parameter to validate URLs in the entire request body without JSONPath extraction. +- **Full payload validation**: Omit the `jsonPath` parameter to validate URLs in the entire request body without JSONPath extraction. -- **Field-Specific Validation**: Use `jsonPath` to extract and validate URLs from specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). +- **Field-specific validation**: Use `jsonPath` to extract and validate URLs from specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). -## Use Cases +## Use cases -1. **Link Validation**: Ensure all URLs in AI-generated content are valid and accessible. +1. **Link validation**: Ensure all URLs in AI-generated content are valid and accessible. 2. **Security**: Detect and block potentially malicious or suspicious URLs. -3. **Quality Assurance**: Prevent broken links from being included in responses. +3. **Quality assurance**: Prevent broken links from being included in responses. -4. **Content Moderation**: Validate URLs before allowing them in user-generated content. +4. **Content moderation**: Validate URLs before allowing them in user-generated content. -5. **Resource Verification**: Ensure referenced resources are available before processing. +5. **Resource verification**: Ensure referenced resources are available before processing. -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: diff --git a/en/docs/ai-gateway/llm-proxy/guardrails/word-count.md b/en/docs/ai-gateway/llm-proxy/guardrails/word-count.md index 78ea643d..0b959e65 100644 --- a/en/docs/ai-gateway/llm-proxy/guardrails/word-count.md +++ b/en/docs/ai-gateway/llm-proxy/guardrails/word-count.md @@ -1,5 +1,5 @@ --- -title: "Word Count Guardrail" +title: "Word count guardrail" description: "Enforce minimum and maximum word count limits on LLM request and response content using the Word Count guardrail." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/word-count/ md_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/guardrails/word-count.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# Word Count Guardrail +# Word count guardrail ## Overview @@ -30,27 +30,27 @@ The Word Count Guardrail validates the word count of request or response body co ### Parameters -#### Request Phase +#### Request phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `min` | integer | Yes | - | Minimum allowed word count (inclusive). Must be >= 0. | | `max` | integer | Yes | - | Maximum allowed word count (inclusive). Must be >= 1. | | `jsonPath` | string | No | `""` | JSONPath expression to extract a specific value from JSON payload. If empty, validates the entire payload as a string. | -| `invert` | boolean | No | `false` | If `true`, validation passes when word count is NOT within the min-max range. If `false`, validation passes when word count is within the range. | +| `invert` | boolean | No | `false` | If `true`, validation passes when word count is not within the min-max range. If `false`, validation passes when word count is within the range. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information in error responses. | -#### Response Phase +#### Response phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `min` | integer | Yes | - | Minimum allowed word count (inclusive). Must be >= 0. | | `max` | integer | Yes | - | Maximum allowed word count (inclusive). Must be >= 1. | | `jsonPath` | string | No | `""` | JSONPath expression to extract a specific value from JSON payload. If empty, validates the entire payload as a string. | -| `invert` | boolean | No | `false` | If `true`, validation passes when word count is NOT within the min-max range. If `false`, validation passes when word count is within the range. | +| `invert` | boolean | No | `false` | If `true`, validation passes when word count is not within the min-max range. If `false`, validation passes when word count is within the range. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information in error responses. | -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and validate specific fields within JSON payloads. Common examples: @@ -63,7 +63,7 @@ If `jsonPath` is empty or not specified, the entire payload is treated as a stri ## Examples -### Example 1: Basic Word Count Validation +### Example 1: Basic word count validation Deploy an LLM provider that validates request messages contain between 10 and 500 words: @@ -112,7 +112,7 @@ EOF **Test the guardrail:** -**Note**: Ensure that "openai" is mapped to the appropriate IP address (e.g., 127.0.0.1) in your `/etc/hosts` file, or remove the vhost from the llm provider configuration and use localhost to invoke. +**Note**: Ensure that "openai" is mapped to the appropriate IP address (e.g., 127.0.0.1) in your `/etc/hosts` file, or remove the vhost from the LLM provider configuration and use localhost to invoke. ```bash # Valid request (should pass) @@ -144,30 +144,30 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Additional Configuration Options +### Additional configuration options You can customize the guardrail behavior by modifying the `policies` section: -- **Request and Response Validation**: Configure both `request` and `response` parameters to validate word counts in both directions. Use `showAssessment: true` to include detailed assessment information in error responses. +- **Request and response validation**: Configure both `request` and `response` parameters to validate word counts in both directions. Use `showAssessment: true` to include detailed assessment information in error responses. -- **Inverted Logic**: Set `invert: true` to allow only content *outside* the specified word range. This is useful for blocking content that falls within a prohibited range. +- **Inverted logic**: Set `invert: true` to allow only content *outside* the specified word range. This is useful for blocking content that falls within a prohibited range. -- **Full Payload Validation**: Omit the `jsonPath` parameter to validate the entire request body without JSONPath extraction. +- **Full payload validation**: Omit the `jsonPath` parameter to validate the entire request body without JSONPath extraction. -- **Field-Specific Validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). +- **Field-specific validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). -## Use Cases +## Use cases -1. **Input Length Control**: Prevent users from submitting extremely long prompts that could impact system performance or costs. +1. **Input length control**: Prevent users from submitting extremely long prompts that could impact system performance or costs. -2. **Response Quality Assurance**: Ensure AI-generated responses meet minimum length requirements for completeness. +2. **Response quality assurance**: Ensure AI-generated responses meet minimum length requirements for completeness. -3. **Cost Management**: Limit response lengths to control token usage and associated costs. +3. **Cost management**: Limit response lengths to control token usage and associated costs. -4. **Content Filtering**: Use inverted logic to block content that falls outside acceptable word count ranges. +4. **Content filtering**: Use inverted logic to block content that falls outside acceptable word count ranges. -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: diff --git a/en/docs/ai-gateway/llm-proxy/llm-templates.md b/en/docs/ai-gateway/llm-proxy/llm-templates.md index b79b0597..9ccfba5b 100644 --- a/en/docs/ai-gateway/llm-proxy/llm-templates.md +++ b/en/docs/ai-gateway/llm-proxy/llm-templates.md @@ -1,5 +1,5 @@ --- -title: "LLM Provider Templates" +title: "LLM provider templates" description: "Reference for LLM Provider Templates in API Platform AI Gateway, covering built-in templates for OpenAI, Anthropic, Gemini, and more." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/llm-templates/ md_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/llm-templates.md @@ -12,17 +12,17 @@ last_updated: 2026-06-16 content_type: "reference" --- -# LLM Provider Templates +# LLM provider templates ## Overview LLM Provider Templates define the characteristics and behaviors specific to an AI service provider, such as OpenAI, Azure OpenAI, Anthropic, or other LLM platforms. These templates describe how the gateway should interpret and extract usage and operational metadata from LLM provider responses, including: -- **Token Usage Metrics**: Prompt tokens, completion tokens, total tokens, and remaining tokens -- **Model Information**: Request and response model identifiers -- **Rate Limiting Data**: Remaining token allowances from response +- **Token usage metrics**: Prompt tokens, completion tokens, total tokens, and remaining tokens +- **Model information**: Request and response model identifiers +- **Rate limiting data**: Remaining token allowances from response -## Out-of-the-Box Supported Templates +## Out-of-the-box supported templates The API Platform Gateway ships with the following pre-configured LLM provider templates that platform administrators can use immediately without any additional configuration: @@ -38,7 +38,7 @@ The API Platform Gateway ships with the following pre-configured LLM provider te These templates are automatically loaded when the gateway starts and are immediately available for use when creating LLM providers. -## Template Structure +## Template structure Each LLM provider template follows a standard YAML structure: @@ -70,7 +70,7 @@ spec: identifier: ``` -### Metadata Extraction Patterns +### Metadata extraction patterns Templates support three types of extraction locations: @@ -78,7 +78,7 @@ Templates support three types of extraction locations: - **`header`**: Extract from HTTP response headers using header name (e.g., `x-ratelimit-remaining-tokens`) - **`pathParam`**: Extract from URL path using regular expressions (e.g., `(?<=models/)[a-zA-Z0-9.\-]+`) -## Template Details +## Template details ### OpenAI @@ -291,7 +291,7 @@ spec: identifier: $.model ``` -## Creating an LLM Provider with a Template +## Creating an LLM provider with a template To create an LLM provider using any of the out-of-the-box templates: @@ -339,9 +339,9 @@ The gateway automatically uses the template's metadata extraction patterns to: - Enable token-based rate limiting policies - Provide consistent monitoring across different LLM providers -## Managing Templates +## Managing templates -### Listing Available Templates +### Listing available templates To list all available LLM provider templates: @@ -350,7 +350,7 @@ curl -X GET http://localhost:9090/api/management/v0.9/llm-provider-templates \ -H "Authorization: Basic YWRtaW46YWRtaW4=" ``` -### Retrieving a Specific Template +### Retrieving a specific template To retrieve details of a specific template: @@ -359,7 +359,7 @@ curl -X GET http://localhost:9090/api/management/v0.9/llm-provider-templates/ope -H "Authorization: Basic YWRtaW46YWRtaW4=" ``` -### Creating Custom Templates +### Creating custom templates Platform administrators can create custom templates for LLM providers not covered by the out-of-the-box templates: @@ -380,7 +380,7 @@ spec: EOF ``` -### Updating Templates +### Updating templates To update an existing custom template: @@ -402,7 +402,7 @@ spec: EOF ``` -### Deleting Custom Templates +### Deleting custom templates To delete a custom template: @@ -413,7 +413,7 @@ curl -X DELETE http://localhost:9090/api/management/v0.9/llm-provider-templates/ **Note**: Out-of-the-box templates cannot be deleted or modified. Only custom templates created by platform administrators can be updated or deleted. -## Template Field Reference +## Template field reference | Field | Type | Required | Description | |-------|------|----------|-------------| @@ -428,7 +428,7 @@ curl -X DELETE http://localhost:9090/api/management/v0.9/llm-provider-templates/ | `spec.requestModel` | object | No | Configuration for extracting request model identifier | | `spec.responseModel` | object | No | Configuration for extracting response model identifier | -### Extraction Configuration Object +### Extraction configuration object Each extraction configuration object has the following structure: diff --git a/en/docs/ai-gateway/llm-proxy/load-balancing/model-round-robin.md b/en/docs/ai-gateway/llm-proxy/load-balancing/model-round-robin.md index 65106864..338d69ad 100644 --- a/en/docs/ai-gateway/llm-proxy/load-balancing/model-round-robin.md +++ b/en/docs/ai-gateway/llm-proxy/load-balancing/model-round-robin.md @@ -1,5 +1,5 @@ --- -title: "Model Round Robin" +title: "Model round robin" description: "Distribute LLM requests evenly across multiple AI models in a cyclic round-robin pattern with automatic failure suspension." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/load-balancing/model-round-robin/ md_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/load-balancing/model-round-robin.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# Model Round Robin +# Model round robin ## Overview @@ -35,7 +35,7 @@ The Model Round Robin policy implements round-robin load balancing for AI models | `models` | array | Yes | - | List of models for round-robin distribution. Each model must have a `model` name. | | `suspendDuration` | integer | No | `0` | Suspend duration in seconds for failed models. If set to 0, failed model knowledge is not persisted. Must be >= 0. | -### Model Configuration +### Model configuration Each model in the `models` array is an object with the following properties: @@ -52,17 +52,17 @@ The policy requires `requestModel` configuration from the LLM provider template | `requestModel.location` | string | Yes | Location of the model identifier: `payload`, `header`, `queryParam`, or `pathParam` | | `requestModel.identifier` | string | Yes | JSONPath (for payload), header name (for header), query param name (for queryParam), or regex pattern (for pathParam) to extract model | -## How It Works +## How it works -1. **Model Selection**: On each request, the policy selects the next available model in the configured list using a round-robin algorithm. -2. **Model Extraction**: The policy extracts the original model from the request (if configured) and stores it for reference. -3. **Model Modification**: The policy modifies the request to use the selected model based on the `requestModel` configuration. -4. **Failure Handling**: If a model returns a 5xx or 429 response, and `suspendDuration` is configured, the model is suspended for the specified duration. -5. **Availability Check**: Suspended models are skipped during selection until their suspension period expires. +1. **Model selection**: On each request, the policy selects the next available model in the configured list using a round-robin algorithm. +2. **Model extraction**: The policy extracts the original model from the request (if configured) and stores it for reference. +3. **Model modification**: The policy modifies the request to use the selected model based on the `requestModel` configuration. +4. **Failure handling**: If a model returns a 5xx or 429 response, and `suspendDuration` is configured, the model is suspended for the specified duration. +5. **Availability check**: Suspended models are skipped during selection until their suspension period expires. ## Examples -### Example 1: Basic Round Robin with Payload-based Model +### Example 1: Basic round robin with payload-based model Deploy an LLM provider with round-robin load balancing across multiple models: @@ -154,33 +154,33 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -## Model Suspension +## Model suspension When a model returns a 5xx or 429 response, the policy can automatically suspend that model for a configurable duration: -- **Suspension Duration**: Configured via the `suspendDuration` parameter (in seconds) -- **Automatic Recovery**: Suspended models are automatically re-enabled after the suspension period expires -- **Availability Check**: Suspended models are skipped during round-robin selection until they recover +- **Suspension duration**: Configured via the `suspendDuration` parameter (in seconds) +- **Automatic recovery**: Suspended models are automatically re-enabled after the suspension period expires +- **Availability check**: Suspended models are skipped during round-robin selection until they recover -### Suspension Behavior +### Suspension behavior - Suspension is tracked per model across all requests - If all models are suspended, the policy returns HTTP 503 with error: "All models are currently unavailable" - Suspension period starts from the time of failure -## Use Cases +## Use cases -1. **Load Distribution**: Distribute requests evenly across multiple models to prevent overloading any single model. +1. **Load distribution**: Distribute requests evenly across multiple models to prevent overloading any single model. -2. **High Availability**: Automatically route requests to available models when some models are experiencing issues. +2. **High availability**: Automatically route requests to available models when some models are experiencing issues. -3. **Cost Optimization**: Distribute requests across different model tiers (e.g., expensive and cheaper models) to balance cost and performance. +3. **Cost optimization**: Distribute requests across different model tiers (e.g., expensive and cheaper models) to balance cost and performance. -4. **A/B Testing**: Test different models with equal traffic distribution to compare performance and quality. +4. **A/B testing**: Test different models with equal traffic distribution to compare performance and quality. -5. **Multi-Provider Support**: Distribute requests across models from different providers while maintaining equal distribution. +5. **Multi-provider support**: Distribute requests across models from different providers while maintaining equal distribution. -## Request Model Locations +## Request model locations The policy supports extracting the model identifier from different locations in the request: @@ -198,14 +198,14 @@ Extract model from HTTP header: - **Location**: `header` - **Identifier**: Header name (e.g., `X-Model-Name`, `X-LLM-Model`) -### Query Parameter +### Query parameter Extract model from URL query parameter: - **Location**: `queryParam` - **Identifier**: Query parameter name (e.g., `model`, `llm_model`) -### Path Parameter +### Path parameter Extract model from URL path using regex: diff --git a/en/docs/ai-gateway/llm-proxy/load-balancing/model-weighted-round-robin.md b/en/docs/ai-gateway/llm-proxy/load-balancing/model-weighted-round-robin.md index 6e771327..8cb32adf 100644 --- a/en/docs/ai-gateway/llm-proxy/load-balancing/model-weighted-round-robin.md +++ b/en/docs/ai-gateway/llm-proxy/load-balancing/model-weighted-round-robin.md @@ -1,5 +1,5 @@ --- -title: "Model Weighted Round Robin" +title: "Model weighted round robin" description: "Distribute LLM requests across AI models by assigned weights, giving higher-capacity or lower-cost models proportionally more traffic." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/load-balancing/model-weighted-round-robin/ md_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/load-balancing/model-weighted-round-robin.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# Model Weighted Round Robin +# Model weighted round robin ## Overview @@ -36,7 +36,7 @@ The Model Weighted Round Robin policy implements weighted round-robin load balan | `models` | array | Yes | - | List of models with weights for weighted round-robin distribution. Each model must have a `model` name and `weight`. | | `suspendDuration` | integer | No | `0` | Suspend duration in seconds for failed models. If set to 0, failed model knowledge is not persisted. Must be >= 0. | -### Model Configuration +### Model configuration Each model in the `models` array is an object with the following properties: @@ -54,16 +54,16 @@ The policy requires `requestModel` configuration from the LLM provider template | `requestModel.location` | string | Yes | Location of the model identifier: `payload`, `header`, `queryParam`, or `pathParam` | | `requestModel.identifier` | string | Yes | JSONPath (for payload), header name (for header), query param name (for queryParam), or regex pattern (for pathParam) to extract model | -## How It Works +## How it works -1. **Weight Calculation**: During policy initialization, the policy calculates the total weight of all configured models and builds a weighted sequence where each model appears a number of times proportional to its weight. This sequence is built once and reused for all requests. -2. **Model Selection**: On each request, the policy selects the next available model from the pre-computed weighted sequence using a round-robin algorithm. -3. **Model Extraction**: The policy extracts the original model from the request using the `requestModel` configuration and stores it for reference. -4. **Model Modification**: The policy modifies the request to use the selected model based on the `requestModel` configuration. -5. **Failure Handling**: If a model returns a 5xx or 429 response, and `suspendDuration` is configured, the model is suspended for the specified duration. -6. **Availability Check**: Suspended models are skipped during selection until their suspension period expires. +1. **Weight calculation**: During policy initialization, the policy calculates the total weight of all configured models and builds a weighted sequence where each model appears a number of times proportional to its weight. This sequence is built once and reused for all requests. +2. **Model selection**: On each request, the policy selects the next available model from the pre-computed weighted sequence using a round-robin algorithm. +3. **Model extraction**: The policy extracts the original model from the request using the `requestModel` configuration and stores it for reference. +4. **Model modification**: The policy modifies the request to use the selected model based on the `requestModel` configuration. +5. **Failure handling**: If a model returns a 5xx or 429 response, and `suspendDuration` is configured, the model is suspended for the specified duration. +6. **Availability check**: Suspended models are skipped during selection until their suspension period expires. -### Weight Distribution Example +### Weight distribution example If you configure three models with weights: - Model A: weight 3 @@ -77,7 +77,7 @@ The weighted sequence would be: `[A, A, A, B, B, C]`, meaning: ## Examples -### Example 1: Basic Weighted Round Robin with Payload-based Model +### Example 1: Basic weighted round robin with payload-based model Deploy an LLM provider with weighted round-robin load balancing: @@ -144,36 +144,36 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -## Model Suspension +## Model suspension When a model returns a 5xx or 429 response, the policy can automatically suspend that model for a configurable duration: -- **Suspension Duration**: Configured via the `suspendDuration` parameter (in seconds) -- **Automatic Recovery**: Suspended models are automatically re-enabled after the suspension period expires -- **Availability Check**: Suspended models are skipped during weighted round-robin selection until they recover -- **Weight Preservation**: When a model is suspended, the remaining models continue to be selected based on their relative weights +- **Suspension duration**: Configured via the `suspendDuration` parameter (in seconds) +- **Automatic recovery**: Suspended models are automatically re-enabled after the suspension period expires +- **Availability check**: Suspended models are skipped during weighted round-robin selection until they recover +- **Weight preservation**: When a model is suspended, the remaining models continue to be selected based on their relative weights -### Suspension Behavior +### Suspension behavior - If all models are suspended, the policy returns HTTP 503 with error: "All models are currently unavailable" - Suspension period starts from the time of failure - When a model is suspended, the weighted sequence is dynamically adjusted to exclude that model -## Use Cases +## Use cases -1. **Capacity-Based Distribution**: Distribute requests based on model capacity, giving higher weights to models that can handle more load. +1. **Capacity-based distribution**: Distribute requests based on model capacity, giving higher weights to models that can handle more load. -2. **Cost Optimization**: Route more requests to cheaper models while maintaining some traffic to premium models for quality assurance. +2. **Cost optimization**: Route more requests to cheaper models while maintaining some traffic to premium models for quality assurance. -3. **Performance Tiers**: Prioritize high-performance models for critical requests while using standard models for regular traffic. +3. **Performance tiers**: Prioritize high-performance models for critical requests while using standard models for regular traffic. -4. **Gradual Migration**: Gradually shift traffic from old models to new models by adjusting weights over time. +4. **Gradual migration**: Gradually shift traffic from old models to new models by adjusting weights over time. -5. **Multi-Provider Balancing**: Distribute requests across models from different providers with different weights based on SLA or cost agreements. +5. **Multi-provider balancing**: Distribute requests across models from different providers with different weights based on SLA or cost agreements. -6. **A/B Testing with Bias**: Test different models with weighted traffic distribution to compare performance while maintaining a bias toward preferred models. +6. **A/B testing with bias**: Test different models with weighted traffic distribution to compare performance while maintaining a bias toward preferred models. -## Request Model Locations +## Request model locations The policy supports extracting the model identifier from different locations in the request: @@ -191,14 +191,14 @@ Extract model from HTTP header: - **Location**: `header` - **Identifier**: Header name (e.g., `X-Model-Name`, `X-LLM-Model`) -### Query Parameter +### Query parameter Extract model from URL query parameter: - **Location**: `queryParam` - **Identifier**: Query parameter name (e.g., `model`, `llm_model`) -### Path Parameter +### Path parameter Extract model from URL path using regex: @@ -207,16 +207,16 @@ Extract model from URL path using regex: **Note**: For path parameters, the regex pattern should include a capturing group to extract the model name. The policy uses the first capturing group as the model identifier. -## Weight Calculation +## Weight calculation The policy builds a weighted sequence by repeating each model a number of times equal to its weight: -- **Total Weight**: Sum of all model weights -- **Sequence Length**: Equal to the total weight +- **Total weight**: Sum of all model weights +- **Sequence length**: Equal to the total weight - **Distribution**: Each model appears in the sequence `weight` times -- **Proportional Selection**: Over time, each model receives requests proportional to `model_weight / total_weight` +- **Proportional selection**: Over time, each model receives requests proportional to `model_weight / total_weight` -### Example Weight Distribution +### Example weight distribution For models with weights [5, 3, 2]: - Total weight: 10 diff --git a/en/docs/ai-gateway/llm-proxy/prompt-management/prompt-decorator.md b/en/docs/ai-gateway/llm-proxy/prompt-management/prompt-decorator.md index 665faa07..3bf00478 100644 --- a/en/docs/ai-gateway/llm-proxy/prompt-management/prompt-decorator.md +++ b/en/docs/ai-gateway/llm-proxy/prompt-management/prompt-decorator.md @@ -1,5 +1,5 @@ --- -title: "Prompt Decorator" +title: "Prompt decorator" description: "Prepend or append custom content to LLM prompts, injecting system messages or standard instructions before requests reach the model." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/prompt-management/prompt-decorator/ md_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/prompt-management/prompt-decorator.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# Prompt Decorator +# Prompt decorator ## Overview @@ -36,15 +36,15 @@ The Prompt Decorator policy dynamically modifies prompts by prepending or append | `jsonPath` | string | Yes | - | JSONPath expression to locate the field to decorate. Use `$.messages[0].content` for text decoration, or `$.messages` for chat decoration. | | `append` | boolean | No | `false` | If `true`, decoration is appended to the content. If `false`, decoration is prepended (default). | -## Decoration Modes +## Decoration modes -### Mode 1: Text Prompt Decoration +### Mode 1: Text prompt decoration Text decoration is used when the JSONPath targets a string field (e.g., `$.messages[0].content`). The decoration can be: - A simple string that gets prepended or appended to the content - An array of decoration objects (their content fields are concatenated with newlines) -**Configuration Example:** +**Configuration example:** ```json { "decoration": "Summarize the following content in a concise, neutral, and professional tone. Structure the summary using bullet points if appropriate.\n\n" @@ -55,11 +55,11 @@ Text decoration is used when the JSONPath targets a string field (e.g., `$.messa - Decoration string is prepended or appended to the target content field - A space is automatically added between the decoration and original content -### Mode 2: Chat Prompt Decoration +### Mode 2: Chat prompt decoration Chat decoration is used when the JSONPath targets an array field (e.g., `$.messages`). The decoration must be an array of message objects: -**Configuration Example:** +**Configuration example:** ```json { "decoration": [ @@ -76,7 +76,7 @@ Chat decoration is used when the JSONPath targets an array field (e.g., `$.messa - Each decoration object must have `role` and `content` fields - Multiple decoration messages can be added -## JSONPath Support +## JSONPath support The decorator supports JSONPath expressions to target specific fields. Common examples: @@ -85,13 +85,13 @@ The decorator supports JSONPath expressions to target specific fields. Common ex - `$.messages` - Entire messages array (chat decoration) - `$.data.text` - Nested text field (text decoration) -**Array Index Syntax:** +**Array index syntax:** - Use `[0]` for first element, `[1]` for second, etc. - Use `[-1]` for last element, `[-2]` for second-to-last, etc. ## Examples -### Example 1: Text Prompt Decoration - Summarization Directive +### Example 1: Text prompt decoration - summarization directive Add a summarization instruction to user prompts: @@ -164,7 +164,7 @@ curl -X POST http://openai:8080/chat/completions \ # } ``` -### Example 2: Chat Prompt Decoration - System Persona +### Example 2: Chat prompt decoration - system persona Add a system message to define AI behavior: @@ -239,7 +239,7 @@ curl -X POST http://openai:8080/chat/completions \ # } ``` -### Example 3: Append Mode - Adding Suffix Instructions +### Example 3: Append mode - adding suffix instructions Append instructions to the end of user messages: @@ -256,25 +256,25 @@ policies: append: true ``` -## Use Cases +## Use cases -1. **Consistent Instructions**: Prepend standardized instructions or guidelines to all prompts to ensure consistent AI behavior. +1. **Consistent instructions**: Prepend standardized instructions or guidelines to all prompts to ensure consistent AI behavior. -2. **System Personas**: Inject system messages to define AI personality, role, or behavior before user interactions. +2. **System personas**: Inject system messages to define AI personality, role, or behavior before user interactions. -3. **Quality Enhancement**: Add formatting instructions (e.g., "respond in bullet points", "use professional tone") to improve response quality. +3. **Quality enhancement**: Add formatting instructions (e.g., "respond in bullet points", "use professional tone") to improve response quality. -4. **Context Addition**: Prepend contextual information or background details to enrich prompts. +4. **Context addition**: Prepend contextual information or background details to enrich prompts. -5. **Multi-turn Conversations**: Add system messages at the beginning of chat conversations to set conversation rules. +5. **Multi-turn conversations**: Add system messages at the beginning of chat conversations to set conversation rules. 6. **Compliance**: Append compliance-related instructions or disclaimers to prompts. -7. **Output Formatting**: Add instructions for specific output formats (JSON, markdown, structured text) to prompts. +7. **Output formatting**: Add instructions for specific output formats (JSON, markdown, structured text) to prompts. -## Configuration Reference +## Configuration reference -### Text Decoration Configuration +### Text decoration configuration ```json { @@ -285,7 +285,7 @@ policies: - Simple string that will be prepended or appended to the target content - A space is automatically added between decoration and original content -### Chat Decoration Configuration +### Chat decoration configuration ```json { @@ -302,7 +302,7 @@ policies: - Each object must have `role` (e.g., "system", "user", "assistant") and `content` fields - Messages are prepended or appended to the messages array in the order specified -## Error Response +## Error response When the policy encounters an error (e.g., invalid JSONPath, missing fields), it returns an HTTP 500 status code with the following structure: diff --git a/en/docs/ai-gateway/llm-proxy/prompt-management/prompt-template.md b/en/docs/ai-gateway/llm-proxy/prompt-management/prompt-template.md index 234d80c7..bee3bda8 100644 --- a/en/docs/ai-gateway/llm-proxy/prompt-management/prompt-template.md +++ b/en/docs/ai-gateway/llm-proxy/prompt-management/prompt-template.md @@ -1,5 +1,5 @@ --- -title: "Prompt Template" +title: "Prompt template" description: "Replace 'template://' URI patterns in LLM request payloads with predefined, parameterized prompt templates." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/prompt-management/prompt-template/ md_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/prompt-management/prompt-template.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# Prompt Template +# Prompt template ## Overview @@ -34,7 +34,7 @@ The Prompt Template policy enables dynamic prompt transformation by replacing `t |-----------|------|----------|---------|-------------| | `promptTemplateConfig` | string | Yes | - | JSON string containing an array of template objects. Each template must have a `name` and `prompt` field. Example: `[{"name": "translate", "prompt": "Translate from [[from]] to [[to]]: [[text]]"}]` | -### Template Configuration Format +### Template configuration format The `promptTemplateConfig` must be a JSON array of template objects: @@ -51,9 +51,9 @@ Each template object contains: - **name**: Unique identifier for the template (used in `template://` URIs) - **prompt**: The template string with `[[parameter-name]]` placeholders that will be replaced -## Template Syntax +## Template syntax -### Template URI Format +### Template URI format Templates are referenced in JSON payloads using the following URI format: @@ -66,7 +66,7 @@ Example: template://translate?from=english&to=spanish&text=Hello world ``` -### Placeholder Syntax +### Placeholder syntax Within template prompts, use double square brackets to define placeholders: @@ -88,7 +88,7 @@ Translate the following text from english to spanish: Hello ## Examples -### Example 1: Translation Template +### Example 1: Translation template Deploy an LLM provider with a translation prompt template: @@ -161,7 +161,7 @@ The policy will transform the request to: } ``` -### Example 2: Summarization Template +### Example 2: Summarization template Create a template for summarizing content with configurable length: @@ -218,7 +218,7 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Example 3: Multiple Templates +### Example 3: Multiple templates Configure multiple templates in a single policy: @@ -247,19 +247,19 @@ policies: ] ``` -## Use Cases +## Use cases -1. **Standardized Prompts**: Ensure consistent prompt formatting across different API consumers by centralizing prompt definitions. +1. **Standardized prompts**: Ensure consistent prompt formatting across different API consumers by centralizing prompt definitions. -2. **Reusable Templates**: Create library of common prompts (translation, summarization, explanation) that can be reused across multiple APIs. +2. **Reusable templates**: Create library of common prompts (translation, summarization, explanation) that can be reused across multiple APIs. -3. **Parameterized Prompts**: Allow dynamic content insertion while maintaining consistent prompt structure and quality. +3. **Parameterized prompts**: Allow dynamic content insertion while maintaining consistent prompt structure and quality. -4. **Multi-language Support**: Use templates with language parameters to standardize prompts for different locales. +4. **Multi-language support**: Use templates with language parameters to standardize prompts for different locales. -5. **Prompt Versioning**: Update prompt templates centrally without requiring changes to client applications. +5. **Prompt versioning**: Update prompt templates centrally without requiring changes to client applications. -## Template Pattern Matching +## Template pattern matching The policy uses regex pattern matching to find `template://` URIs in the JSON payload: @@ -267,14 +267,14 @@ The policy uses regex pattern matching to find `template://` URIs in the JSON pa - **Location**: Searches the entire JSON payload as a string - **Replacement**: Each matched pattern is replaced with the resolved template string (JSON-escaped) -### Pattern Details +### Pattern details - Template names can contain letters, numbers, underscores, and hyphens - Query parameters can contain any characters except spaces, quotes, or single quotes - Multiple template:// patterns can exist in a single payload - Each pattern is resolved independently -## Error Handling +## Error handling If a template:// pattern references a template name that doesn't exist in the configuration, the pattern is left unchanged (no replacement occurs). This allows for graceful handling of missing templates. diff --git a/en/docs/ai-gateway/llm-proxy/quick-start-guide.md b/en/docs/ai-gateway/llm-proxy/quick-start-guide.md index 63b3b0c5..d4498f8f 100644 --- a/en/docs/ai-gateway/llm-proxy/quick-start-guide.md +++ b/en/docs/ai-gateway/llm-proxy/quick-start-guide.md @@ -1,5 +1,5 @@ --- -title: "LLM Proxy Quick Start Guide" +title: "LLM proxy quick start guide" description: "Run API Platform AI Gateway with Docker Compose, configure an LLM provider, and route your first LLM request through a managed proxy." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/quick-start-guide/ md_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/quick-start-guide.md @@ -12,9 +12,9 @@ last_updated: 2026-06-11 content_type: "quickstart" --- -## Quick Start +## Quick start -### Using Docker Compose (Recommended) +### Using Docker compose (recommended) ### Prerequisites @@ -52,7 +52,7 @@ curl http://localhost:9094/health ## Deploy an OpenAI LLM provider configuration -The API Platform Gateway currently includes first-class support for the OpenAI LLM provider. As a platform administrator, replace `` with your openai API key and run the following command to deploy a sample OpenAI LLM provider. +The API Platform Gateway currently includes first-class support for the OpenAI LLM provider. As a platform administrator, replace `` with your OpenAI API key and run the following command to deploy a sample OpenAI LLM provider. ```bash curl -X POST http://localhost:9090/api/management/v0.9/llm-providers \ @@ -141,7 +141,7 @@ curl -X POST "https://localhost:8443/assistant/chat/completions" \ }' -k ``` -## Stopping the Gateway +## Stopping the gateway When stopping the gateway, you have two options: diff --git a/en/docs/ai-gateway/llm-proxy/semantic-caching.md b/en/docs/ai-gateway/llm-proxy/semantic-caching.md index 27ef54a1..2bc934e1 100644 --- a/en/docs/ai-gateway/llm-proxy/semantic-caching.md +++ b/en/docs/ai-gateway/llm-proxy/semantic-caching.md @@ -1,5 +1,5 @@ --- -title: "Semantic Caching" +title: "Semantic caching" description: "Cache LLM responses using vector similarity search so semantically similar queries are served from cache, reducing cost and latency." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/semantic-caching/ md_url: https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/semantic-caching.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# Semantic Caching +# Semantic caching ## Overview @@ -31,37 +31,37 @@ The policy uses embedding models to convert request text into high-dimensional v - **Immediate response on cache hit**: Returns cached response with `X-Cache-Status: HIT` header without upstream call - **TTL support**: Configurable time-to-live for cache entries -## How It Works +## How it works -### Request Phase +### Request phase -1. **Text Extraction**: Extracts text from the request body using JSONPath (if configured) or uses the entire request body -2. **Embedding Generation**: Generates a vector embedding from the extracted text using the configured embedding provider -3. **Cache Lookup**: Searches the vector database for semantically similar cached responses using cosine similarity -4. **Threshold Check**: If a similar embedding is found with similarity >= similarityThreshold, returns the cached response immediately -5. **Cache Miss**: If no similar response is found, the request proceeds to the upstream service +1. **Text extraction**: Extracts text from the request body using JSONPath (if configured) or uses the entire request body +2. **Embedding generation**: Generates a vector embedding from the extracted text using the configured embedding provider +3. **Cache lookup**: Searches the vector database for semantically similar cached responses using cosine similarity +4. **Threshold check**: If a similar embedding is found with similarity >= similarityThreshold, returns the cached response immediately +5. **Cache miss**: If no similar response is found, the request proceeds to the upstream service -### Response Phase +### Response phase -1. **Success Check**: Only processes responses with 200 status codes -2. **Embedding Retrieval**: Retrieves the embedding generated during the request phase from metadata -3. **Response Storage**: Stores the response payload along with its embedding in the vector database -4. **TTL Application**: Applies the configured TTL to the cache entry +1. **Success check**: Only processes responses with 200 status codes +2. **Embedding retrieval**: Retrieves the embedding generated during the request phase from metadata +3. **Response storage**: Stores the response payload along with its embedding in the vector database +4. **TTL application**: Applies the configured TTL to the cache entry ## Configuration -### Policy Parameters +### Policy parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `similarityThreshold` | number | Yes | - | Similarity threshold for cache hits (0.0 to 1.0). Higher values require more similarity. For example, 0.9 means 90% similarity required. Recommended: 0.85-0.95 for strict matching, 0.70-0.85 for more flexible matching. | | `jsonPath` | string | No | `""` | JSONPath expression to extract text from request body for embedding generation. If empty, uses the entire request body. Example: `"$.messages[0].content"` to extract the first message's content. | -### System Parameters (Required) +### System parameters (required) -These parameters are typically configured at the gateway level and automatically injected, or you can override those values from the params section in the api artifact definition file as well: +These parameters are typically configured at the gateway level and automatically injected, or you can override those values from the params section in the API artifact definition file: -#### Embedding Provider Configuration +#### Embedding provider configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| @@ -71,7 +71,7 @@ These parameters are typically configured at the gateway level and automatically | `embeddingDimension` | integer | Yes | Dimension of embedding vectors. Common values: 1536 (OpenAI ada-002), 1024 (Mistral). Must match the model's output dimension. | | `apiKey` | string | Yes | API key for the embedding service authentication. The authentication header is automatically set to `api-key` for Azure OpenAI and `Authorization` for other providers. | -#### Vector Database Configuration +#### Vector database configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| @@ -84,7 +84,7 @@ These parameters are typically configured at the gateway level and automatically | `ttl` | integer | No | Time-to-live for cache entries in seconds. Default is 3600 (1 hour). Set to 0 for no expiration. | -### Configuring System Parameters in config.toml +### Configuring system parameters in config.toml System parameters can be configured globally in the gateway's `config.toml` file. These values serve as defaults for all Semantic Cache policy instances and can be overridden per-policy in the API configuration if needed. @@ -108,14 +108,14 @@ vector_db_provider_password = "default" vector_db_provider_ttl = 3600 ``` -## JSONPath Support +## JSONPath support The policy supports JSONPath expressions to extract specific text from request bodies before generating embeddings. This is useful for: - Extracting message content from chat completion requests - Focusing on specific prompt fields while ignoring metadata - Handling structured JSON payloads -### Common JSONPath Examples +### Common JSONPath examples - `$.messages[0].content` - First message's content in chat completions - `$.messages[-1].content` - Last message's content @@ -125,7 +125,7 @@ The policy supports JSONPath expressions to extract specific text from request b ## Examples -### Example 1: OpenAI Embeddings with Redis +### Example 1: OpenAI embeddings with Redis Deploy an LLM provider with semantic caching using OpenAI embeddings and Redis vector store: @@ -201,25 +201,25 @@ curl -X POST http://openai:8080/chat/completions \ # Response will include: X-Cache-Status: HIT ``` -## Use Cases +## Use cases -1. **Cost Reduction**: Reduce API costs by serving cached responses for similar queries, especially valuable for expensive LLM API calls. +1. **Cost reduction**: Reduce API costs by serving cached responses for similar queries, especially valuable for expensive LLM API calls. -2. **Latency Improvement**: Return cached responses in milliseconds instead of waiting for LLM processing (typically 1-5 seconds), significantly improving user experience. +2. **Latency improvement**: Return cached responses in milliseconds instead of waiting for LLM processing (typically 1-5 seconds), significantly improving user experience. -3. **Rate Limit Management**: Reduce the number of upstream API calls, helping stay within rate limits and avoiding throttling. +3. **Rate limit management**: Reduce the number of upstream API calls, helping stay within rate limits and avoiding throttling. 4. **Consistency**: Ensure users receive consistent responses for semantically equivalent queries, improving predictability. -5. **Offline Resilience**: Serve cached responses even when upstream services experience temporary outages. +5. **Offline resilience**: Serve cached responses even when upstream services experience temporary outages. -6. **A/B Testing**: Compare cached vs. fresh responses to evaluate prompt engineering improvements. +6. **A/B testing**: Compare cached vs. fresh responses to evaluate prompt engineering improvements. -7. **Development/Testing**: Speed up development cycles by reusing cached responses during testing. +7. **Development/testing**: Speed up development cycles by reusing cached responses during testing. -8. **High-Traffic Applications**: Handle high volumes of similar queries efficiently without overwhelming upstream services. +8. **High-traffic applications**: Handle high volumes of similar queries efficiently without overwhelming upstream services. -## Similarity Threshold Guidelines +## Similarity threshold guidelines The `similarityThreshold` parameter controls how similar requests must be to trigger a cache hit: @@ -231,9 +231,9 @@ The `similarityThreshold` parameter controls how similar requests must be to tri **Recommendation**: Start with 0.85 and adjust based on your use case. Monitor cache hit rates and response relevance to fine-tune. -## Cache Behavior +## Cache behavior -### Cache Hit +### Cache hit When a similar request is found: - Returns cached response immediately (no upstream call) @@ -241,44 +241,44 @@ When a similar request is found: - Status code: 200 (from cached response) - Response time: Typically < 50ms (vs. 1-5 seconds for LLM APIs) -### Cache Miss +### Cache miss When no similar request is found: - Request proceeds to upstream service normally - Response is cached after successful upstream call (200 status) - Subsequent similar requests may hit the cache -### Cache Storage +### Cache storage - Only successful responses (200 status code) are cached - Responses are stored with their embeddings in the vector database - TTL is applied to all cache entries - Each route/API maintains a separate cache namespace to avoid cross-contamination -## Error Handling +## Error handling The policy is designed to be resilient: -- **Embedding Generation Failure**: If embedding generation fails, the request proceeds to upstream (cache is skipped) -- **Vector Database Unavailable**: If the vector database is unreachable, requests proceed to upstream -- **Cache Storage Failure**: If storing a response fails, the response is still returned to the client (cache operation is non-blocking) +- **Embedding generation failure**: If embedding generation fails, the request proceeds to upstream (cache is skipped) +- **Vector database unavailable**: If the vector database is unreachable, requests proceed to upstream +- **Cache storage failure**: If storing a response fails, the response is still returned to the client (cache operation is non-blocking) - **Invalid JSONPath**: If JSONPath extraction fails, the entire request body is used for embedding generation These behaviors ensure that caching failures do not block legitimate requests. The system gracefully degrades to direct upstream calls when caching is unavailable. -## Performance Considerations +## Performance considerations -1. **Embedding Generation Latency**: Generating embeddings adds ~100-500ms to request processing. This is offset by cache hits that save 1-5 seconds. +1. **Embedding generation latency**: Generating embeddings adds ~100-500ms to request processing. This is offset by cache hits that save 1-5 seconds. -2. **Vector Database Performance**: +2. **Vector database performance**: - Redis with RedisSearch: Fast queries, good for smaller datasets (< 1M vectors) - Milvus: Optimized for large-scale vector search, better for > 1M vectors -3. **Cache Hit Rate**: Aim for 20-40% cache hit rate for cost-effective caching. Below 10% may not justify the overhead. +3. **Cache hit rate**: Aim for 20-40% cache hit rate for cost-effective caching. Below 10% may not justify the overhead. -4. **Embedding Dimension**: Higher dimensions (e.g., 1536) provide better accuracy but increase storage and search time. Choose based on your quality requirements. +4. **Embedding dimension**: Higher dimensions (e.g., 1536) provide better accuracy but increase storage and search time. Choose based on your quality requirements. -5. **Index Creation**: Vector database indexes are created automatically on first use. This may take a few seconds for large datasets. +5. **Index creation**: Vector database indexes are created automatically on first use. This may take a few seconds for large datasets. ## Notes diff --git a/en/docs/ai-gateway/mcp-proxy/policies/mcp-acl-list.md b/en/docs/ai-gateway/mcp-proxy/policies/mcp-acl-list.md index 377d3fb4..4b03683b 100644 --- a/en/docs/ai-gateway/mcp-proxy/policies/mcp-acl-list.md +++ b/en/docs/ai-gateway/mcp-proxy/policies/mcp-acl-list.md @@ -1,5 +1,5 @@ --- -title: "MCP ACL List" +title: "MCP ACL list" description: "Control access to MCP tools, resources, and prompts using allow or deny mode with exceptions in API Platform AI Gateway." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/mcp-proxy/policies/mcp-acl-list/ md_url: https://wso2.com/api-platform/docs/ai-gateway/mcp-proxy/policies/mcp-acl-list.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# MCP ACL List +# MCP ACL list ## Overview @@ -22,18 +22,18 @@ The policy operates on three types of MCP capabilities: tools, resources, and pr ## Features -- **Tool-Level Access Control**: Allow or deny access to specific tools using allow/deny mode with exceptions. -- **Resource-Level Access Control**: Control access to specific resources (identified by URI) using flexible ACL rules. -- **Prompt-Level Access Control**: Manage access to specific prompts using configurable access modes. -- **Flexible ACL Modes**: Support both allow-with-exceptions and deny-with-exceptions patterns. -- **List Filtering**: Filter list responses to only include capabilities that match the access control rules. -- **Request Path Enforcement**: Enforce the same allow/deny rules on request paths, rejecting access to denied capabilities. +- **Tool-level access control**: Allow or deny access to specific tools using allow/deny mode with exceptions. +- **Resource-level access control**: Control access to specific resources (identified by URI) using flexible ACL rules. +- **Prompt-level access control**: Manage access to specific prompts using configurable access modes. +- **Flexible ACL modes**: Support both allow-with-exceptions and deny-with-exceptions patterns. +- **List filtering**: Filter list responses to only include capabilities that match the access control rules. +- **Request path enforcement**: Enforce the same allow/deny rules on request paths, rejecting access to denied capabilities. ## Configuration The MCP ACL List policy uses a single-level configuration model where all parameters are configured per-MCP-API/route in the API definition YAML. -### User Parameters (API Definition) +### User parameters (API definition) These parameters are configured per MCP Proxy by the API developer: @@ -49,7 +49,7 @@ These parameters are configured per MCP Proxy by the API developer: | `prompts.mode` | string | Yes | ACL mode for prompts: "allow" (allow all except exceptions) or "deny" (deny all except exceptions). | | `prompts.exceptions` | array | No | List of prompt names that are exceptions to the mode (1-256 characters each). | -## Access Control Logic +## Access control logic For each capability type (tools, resources, prompts): @@ -57,9 +57,9 @@ For each capability type (tools, resources, prompts): - **mode: allow, exceptions: [...]**: Allow all capabilities except those listed in exceptions. - **mode: deny, exceptions: [...]**: Deny all capabilities except those listed in exceptions. -## MCP Proxy Definition Examples +## MCP proxy definition examples -### Example 1: Deny Specific Tools +### Example 1: Deny specific tools Deny access to certain tools while allowing all others: @@ -87,7 +87,7 @@ spec: ... ``` -### Example 2: Allow Only Specific Resources +### Example 2: Allow only specific resources Allow access to only whitelisted resources: @@ -115,7 +115,7 @@ spec: ... ``` -### Example 3: Mixed Access Control +### Example 3: Mixed access control Apply different access control rules to different capability types: @@ -152,24 +152,24 @@ spec: ... ``` -## Use Cases +## Use cases -1. **Sensitive Operation Blocking**: Deny access to tools or resources that perform sensitive operations (e.g., delete, modify system configuration). -2. **Public API Restriction**: Allow only specific public resources while denying access to internal resources. -3. **Role-Based Access**: Combine this policy with authentication/authorization policies to implement role-based access control. -4. **Gradual Feature Rollout**: Deny access to beta or experimental tools while they are being tested. -5. **Compliance and Security**: Enforce compliance policies by denying access to resources or tools that are not approved for a specific tenant or environment. -6. **Cost Control**: Deny access to expensive or resource-intensive operations. +1. **Sensitive operation blocking**: Deny access to tools or resources that perform sensitive operations (e.g., delete, modify system configuration). +2. **Public API restriction**: Allow only specific public resources while denying access to internal resources. +3. **Role-based access**: Combine this policy with authentication/authorization policies to implement role-based access control. +4. **Gradual feature rollout**: Deny access to beta or experimental tools while they are being tested. +5. **Compliance and security**: Enforce compliance policies by denying access to resources or tools that are not approved for a specific tenant or environment. +6. **Cost control**: Deny access to expensive or resource-intensive operations. -## Comparison with MCP Rewrite Policy +## Comparison with MCP rewrite policy | Aspect | MCP ACL List | MCP Rewrite | |--------|--------------|-------------| -| **Primary Purpose** | Access control via allow/deny | Capability name mapping | -| **Rewrites Names** | No | Yes | -| **Filters Lists** | Yes | Yes | -| **Enforces Request Paths** | Yes | Yes | -| **Configuration Complexity** | Simple (mode + exceptions) | Detailed (names, descriptions, targets) | -| **Metadata Modification** | No | Yes | +| **Primary purpose** | Access control via allow/deny | Capability name mapping | +| **Rewrites names** | No | Yes | +| **Filters lists** | Yes | Yes | +| **Enforces request paths** | Yes | Yes | +| **Configuration complexity** | Simple (mode + exceptions) | Detailed (names, descriptions, targets) | +| **Metadata modification** | No | Yes | Both policies can be used together: use MCP ACL List for access control and MCP Rewrite for name mapping. diff --git a/en/docs/ai-gateway/mcp-proxy/policies/mcp-authentication.md b/en/docs/ai-gateway/mcp-proxy/policies/mcp-authentication.md index edccb7d4..53d250fe 100644 --- a/en/docs/ai-gateway/mcp-proxy/policies/mcp-authentication.md +++ b/en/docs/ai-gateway/mcp-proxy/policies/mcp-authentication.md @@ -1,5 +1,5 @@ --- -title: "MCP Authentication" +title: "MCP authentication" description: "Secure MCP server traffic by validating JWT access tokens and serving OAuth protected resource metadata in AI Gateway." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/mcp-proxy/policies/mcp-authentication/ md_url: https://wso2.com/api-platform/docs/ai-gateway/mcp-proxy/policies/mcp-authentication.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# MCP Authentication +# MCP authentication ## Overview @@ -20,20 +20,20 @@ The MCP Authentication policy is designed to secure traffic to Model Context Pro ## Features -- **Access Token Validation**: Validates JWT access tokens using configured key managers. Please refer the [JWT Authentication Policy](https://wso2.com/api-platform/policy-hub/policies/jwt-auth) for more information on how the key validation works. -- **Protected Resource Metadata**: Intercepts `GET /.well-known/oauth-protected-resource` requests to return resource metadata, including authorization servers and supported scopes. -- **Standardized Error Handling**: Returns `WWW-Authenticate` headers with `resource_metadata` on authentication failures. -- **Configurable Validation**: Supports issuer, audience, scope, and custom claim validation. -- **Claim Mapping**: Maps token claims to downstream headers. +- **Access token validation**: Validates JWT access tokens using configured key managers. Please refer the [JWT Authentication Policy](https://wso2.com/api-platform/policy-hub/policies/jwt-auth) for more information on how the key validation works. +- **Protected resource metadata**: Intercepts `GET /.well-known/oauth-protected-resource` requests to return resource metadata, including authorization servers and supported scopes. +- **Standardized error handling**: Returns `WWW-Authenticate` headers with `resource_metadata` on authentication failures. +- **Configurable validation**: Supports issuer, audience, scope, and custom claim validation. +- **Claim mapping**: Maps token claims to downstream headers. ## Configuration The MCP Authentication policy uses a two-level configuration model: -- **System Parameters**: Configured by the administrator in `config.toml` under `policy_configurations.mcpauth_v0` or `policy_configurations.jwtauth_v0` depending on the parameter. -- **User Parameters**: Configured per MCP proxy in the configuration yaml. +- **System parameters**: Configured by the administrator in `config.toml` under `policy_configurations.mcpauth_v0` or `policy_configurations.jwtauth_v0` depending on the parameter. +- **User parameters**: Configured per MCP proxy in the configuration yaml. -### System Parameters (config.toml) +### System parameters (config.toml) These parameters are set by the administrator and apply globally to all MCP authentication policies: @@ -42,7 +42,7 @@ These parameters are set by the administrator and apply globally to all MCP auth | `keymanagers` | array | Yes | jwtauth_v0 | List of key manager definitions. Each entry must include a unique `name` and either `jwks` (for remote JWKS or local certificates) configuration. | | `gatewayhost` | string | No | mcpauth_v0 | The outward-facing gateway host name which will be used when deriving the values related to protected resource metadata in headers and body. The gateway will fall back to this if there are no vhosts defined in the MCP proxy configuration. | -#### Key Manager Configuration +#### Key manager configuration Each key manager in the `keymanagers` array supports the following structure: @@ -58,7 +58,7 @@ Each key manager in the `keymanagers` array supports the following structure: > **Note**: Either `jwks.remote` or `jwks.local` must be specified, but not both. -### User Parameters (API Definition) +### User parameters (API definition) These parameters are configured per-API/route by the API developer: @@ -70,7 +70,7 @@ These parameters are configured per-API/route by the API developer: | `requiredClaims` | object | No | - | Map of claimName → expectedValue for custom claim validation. | | `claimMappings` | object | No | - | Map of claimName → downstream header name to expose claims for downstream services. | -## System Configuration Example +## System configuration example Add the following to your `gateway/configs/config.toml` file under `policy_configurations`: @@ -109,9 +109,9 @@ uri = "https://auth.example.org/oauth2/jwks" skipTlsVerify = false ``` -## MCP Proxy Definition Examples +## MCP proxy definition examples -### Example 1: Basic MCP Authentication +### Example 1: Basic MCP authentication Apply MCP authentication to an API using a specific key manager: @@ -137,7 +137,7 @@ spec: ... ``` -### Example 2: Scope and Audience Validation +### Example 2: Scope and audience validation Require specific scopes and audiences: @@ -168,8 +168,8 @@ spec: ... ``` -## Use Cases +## Use cases -1. **MCP Server Security**: Protect Model Context Protocol servers by requiring valid access tokens from trusted identity providers. -2. **Resource Discovery**: Enable MCP clients to discover authorization requirements (authorization servers and scopes) via the standard `.well-known/oauth-protected-resource` endpoint. -3. **Multi-Provider Support**: Allow MCP clients to authenticate using tokens from different identity providers (e.g., different organizations or tenants). +1. **MCP server security**: Protect Model Context Protocol servers by requiring valid access tokens from trusted identity providers. +2. **Resource discovery**: Enable MCP clients to discover authorization requirements (authorization servers and scopes) via the standard `.well-known/oauth-protected-resource` endpoint. +3. **Multi-provider support**: Allow MCP clients to authenticate using tokens from different identity providers (e.g., different organizations or tenants). diff --git a/en/docs/ai-gateway/mcp-proxy/policies/mcp-authorization.md b/en/docs/ai-gateway/mcp-proxy/policies/mcp-authorization.md index 35e84f00..a0e78545 100644 --- a/en/docs/ai-gateway/mcp-proxy/policies/mcp-authorization.md +++ b/en/docs/ai-gateway/mcp-proxy/policies/mcp-authorization.md @@ -1,5 +1,5 @@ --- -title: "MCP Authorization" +title: "MCP authorization" description: "Define fine-grained access control rules for MCP tools, resources, and prompts based on JWT claims and scopes." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/mcp-proxy/policies/mcp-authorization/ md_url: https://wso2.com/api-platform/docs/ai-gateway/mcp-proxy/policies/mcp-authorization.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# MCP Authorization +# MCP authorization ## Overview @@ -22,20 +22,20 @@ The MCP Authorization policy provides fine-grained access control for Model Cont ## Features -- **Tool-Level Access Control**: Restrict access to specific MCP tools based on user claims and scopes -- **Resource-Level Access Control**: Control access to specific MCP resources based on authorization rules -- **Prompt-Level Access Control**: Manage access to specific MCP prompts -- **JSON-RPC Method-Level Access Control**: Apply authorization rules at the JSON-RPC method level (e.g., `tools/call`, `resources/read`, `prompts/get`) for fine-grained control. Only methods under `tools/`, `resources/`, and `prompts/` are evaluated. -- **Flexible Rule-Based Authorization**: Define multiple authorization rules with attribute matching (exact or wildcard) -- **Claim-Based Validation**: Validate custom claims (e.g., department, role, team) in user tokens -- **Scope-Based Validation**: Require specific OAuth scopes for accessing protected resources -- **Wildcard Matching**: Use wildcard patterns ("*") to create default rules for all resources of a type +- **Tool-level access control**: Restrict access to specific MCP tools based on user claims and scopes +- **Resource-level access control**: Control access to specific MCP resources based on authorization rules +- **Prompt-level access control**: Manage access to specific MCP prompts +- **JSON-RPC method-level access control**: Apply authorization rules at the JSON-RPC method level (e.g., `tools/call`, `resources/read`, `prompts/get`) for fine-grained control. Only methods under `tools/`, `resources/`, and `prompts/` are evaluated. +- **Flexible rule-based authorization**: Define multiple authorization rules with attribute matching (exact or wildcard) +- **Claim-based validation**: Validate custom claims (e.g., department, role, team) in user tokens +- **Scope-based validation**: Require specific OAuth scopes for accessing protected resources +- **Wildcard matching**: Use wildcard patterns ("*") to create default rules for all resources of a type ## Configuration The MCP Authorization policy uses a single-level configuration model where all parameters are configured per-MCP-API/route in the API definition YAML. -### User Parameters (API Definition) +### User parameters (API definition) These parameters are configured per MCP Proxy by the API developer: @@ -48,9 +48,9 @@ These parameters are configured per MCP Proxy by the API developer: | `rules[].requiredScopes` | array | No | - | List of OAuth scopes required to access this resource. The token must contain all of the specified scopes. | | `rules[].requiredClaims` | object | No | - | Map of claim names to expected values. All specified claims must be present in the token with matching values. | -## MCP Proxy Definition Examples +## MCP proxy definition examples -### Example 1: Basic Tool Access Control +### Example 1: Basic tool access control Restrict access to specific tools based on scopes: @@ -95,7 +95,7 @@ spec: ... ``` -### Example 2: Claim-Based Resource Access +### Example 2: Claim-based resource access Control resource access based on user claims: @@ -137,7 +137,7 @@ spec: ... ``` -### Example 3: Role-Based Prompt Access +### Example 3: Role-based prompt access Restrict prompt access based on user roles: @@ -179,7 +179,7 @@ spec: ... ``` -### Example 4: Multi-Level Authorization +### Example 4: Multi-level authorization Combine different resource types with varying access requirements: @@ -240,7 +240,7 @@ spec: ... ``` -## Authorization Decision Examples +## Authorization decision examples **Scenario 1**: User with scope `mcp:tool:read` attempts to call `list_files` tool - Rule: `attribute.type="tool", attribute.name="list_files", requiredScopes=["mcp:tool:read"]` @@ -258,14 +258,14 @@ spec: - Rule: `attribute.type="resource", attribute.name="file:///private/code", requiredClaims={department="engineering"}` - Result: ❌ Access Denied (claim mismatch) -## Error Handling +## Error handling When authorization fails, the policy returns: -- **HTTP Status**: `403 Forbidden` -- **Response Body**: JSON error response with a reason message -- **WWW-Authenticate Header**: Contains information about required scopes for the denied resource +- **HTTP status**: `403 Forbidden` +- **Response body**: JSON error response with a reason message +- **WWW-Authenticate header**: Contains information about required scopes for the denied resource -## Related Policies +## Related policies - [MCP Authentication Policy](./mcp-authentication.md) - Validates JWT tokens and is a prerequisite for MCP Authorization - [JWT Authentication Policy](https://wso2.com/api-platform/policy-hub/policies/jwt-auth) - Base JWT token validation mechanism diff --git a/en/docs/ai-gateway/mcp-proxy/policies/mcp-rewrite.md b/en/docs/ai-gateway/mcp-proxy/policies/mcp-rewrite.md index 1ae86dda..05b62e42 100644 --- a/en/docs/ai-gateway/mcp-proxy/policies/mcp-rewrite.md +++ b/en/docs/ai-gateway/mcp-proxy/policies/mcp-rewrite.md @@ -1,5 +1,5 @@ --- -title: "MCP Rewrite" +title: "MCP rewrite" description: "Expose user-facing names for MCP tools, resources, and prompts while mapping them to different backend capability names." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/mcp-proxy/policies/mcp-rewrite/ md_url: https://wso2.com/api-platform/docs/ai-gateway/mcp-proxy/policies/mcp-rewrite.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "reference" --- -# MCP Rewrite +# MCP rewrite ## Overview @@ -22,17 +22,17 @@ When a list is provided for a capability type, only the configured capabilities ## Features -- **Tool Rewriting**: Define user-facing tool names and map them to backend tool names with custom schemas and descriptions. -- **Resource Rewriting**: Define user-facing resource identifiers and map them to backend resource identifiers with custom descriptions. -- **Prompt Rewriting**: Define user-facing prompt names and map them to backend prompt names with custom metadata. -- **Flexible Metadata**: Include additional fields (beyond `name`, `description`, `target`, etc.) in capability definitions for custom metadata in list responses. -- **Optional Mapping**: Omit the `target` field to expose capabilities as-is without mapping to a different backend name. +- **Tool rewriting**: Define user-facing tool names and map them to backend tool names with custom schemas and descriptions. +- **Resource rewriting**: Define user-facing resource identifiers and map them to backend resource identifiers with custom descriptions. +- **Prompt rewriting**: Define user-facing prompt names and map them to backend prompt names with custom metadata. +- **Flexible metadata**: Include additional fields (beyond `name`, `description`, `target`, etc.) in capability definitions for custom metadata in list responses. +- **Optional mapping**: Omit the `target` field to expose capabilities as-is without mapping to a different backend name. ## Configuration The MCP Rewrite policy uses a single-level configuration model where all parameters are configured per-MCP-API/route in the API definition YAML. -### User Parameters (API Definition) +### User parameters (API definition) These parameters are configured per MCP Proxy by the API developer: @@ -56,9 +56,9 @@ These parameters are configured per MCP Proxy by the API developer: > **Note**: Additional custom fields can be included in `tools`, `resources`, and `prompts` definitions and will be returned in the corresponding list responses. -## MCP Proxy Definition Examples +## MCP proxy definition examples -### Example 1: Basic Tool Rewriting +### Example 1: Basic tool rewriting Expose tools with different names than the backend: @@ -90,7 +90,7 @@ spec: ... ``` -### Example 2: Resource Rewriting with URI Mapping +### Example 2: Resource rewriting with URI mapping Expose resources with user-friendly URIs mapped to backend resources: @@ -122,7 +122,7 @@ spec: ... ``` -### Example 3: Prompt and Tool Rewriting Combined +### Example 3: Prompt and tool rewriting combined Rewrite prompts and tools with metadata: @@ -155,7 +155,7 @@ spec: ... ``` -## Use Cases +## Use cases -1. **Semantic Naming**: Use user-friendly names in the API while keeping backend names internal or legacy. -2. **AI Readiness**: Redefine name, description, input schema, etc. in a way that is friendly to the AI agents. +1. **Semantic naming**: Use user-friendly names in the API while keeping backend names internal or legacy. +2. **AI readiness**: Redefine name, description, input schema, etc. in a way that is friendly to the AI agents. diff --git a/en/docs/ai-gateway/mcp-proxy/quick-start-guide.md b/en/docs/ai-gateway/mcp-proxy/quick-start-guide.md index ec1c67b1..b0bb1bb2 100644 --- a/en/docs/ai-gateway/mcp-proxy/quick-start-guide.md +++ b/en/docs/ai-gateway/mcp-proxy/quick-start-guide.md @@ -1,5 +1,5 @@ --- -title: "MCP Proxy Quick Start Guide" +title: "MCP proxy quick start guide" description: "Run API Platform AI Gateway with Docker Compose, configure an MCP proxy, and route your first MCP traffic through the gateway." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/mcp-proxy/quick-start-guide/ md_url: https://wso2.com/api-platform/docs/ai-gateway/mcp-proxy/quick-start-guide.md @@ -12,9 +12,9 @@ last_updated: 2026-06-16 content_type: "quickstart" --- -## Quick Start +## Quick start -### Using Docker Compose (Recommended) +### Using Docker compose (recommended) ### Prerequisites @@ -86,7 +86,7 @@ To test MCP traffic routing through the gateway, add the following URL to your M http://localhost:8080/everything/mcp ``` -## Stopping the Gateway +## Stopping the gateway Stop and remove the MCP backend first. diff --git a/en/docs/ai-gateway/observability/logging.md b/en/docs/ai-gateway/observability/logging.md index b7a77e68..455f4037 100644 --- a/en/docs/ai-gateway/observability/logging.md +++ b/en/docs/ai-gateway/observability/logging.md @@ -1,5 +1,5 @@ --- -title: "Gateway Logging" +title: "Gateway logging" description: "Configure centralized log collection for API Platform AI Gateway using Fluent Bit, OpenSearch, and alternative logging stacks." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/observability/logging/ md_url: https://wso2.com/api-platform/docs/ai-gateway/observability/logging.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "how-to" --- -# Gateway Logging +# Gateway logging This guide explains how to implement and configure logging for the API Platform Gateway components. @@ -22,7 +22,7 @@ The default logging services included in the Docker Compose configuration are ** **Important**: You are free to choose any logging or observability strategy that suits your environment and requirements. The provided setup is just one of many possible configurations. -## Logging Architecture +## Logging architecture The default logging stack consists of: @@ -30,7 +30,7 @@ The default logging stack consists of: - **OpenSearch**: Stores and indexes log data for searchability and analysis - **OpenSearch Dashboards**: Web interface for visualizing, exploring, and searching logs -### How It Works +### How it works 1. Gateway components (gateway-controller, policy-engine, router) write structured JSON logs to stdout/stderr 2. Docker captures these logs and stores them in `/var/lib/docker/containers` @@ -38,9 +38,9 @@ The default logging stack consists of: 4. Fluent Bit forwards processed logs to OpenSearch 5. Users can view and search logs through OpenSearch Dashboards -## Enabling Logging Services +## Enabling logging services -### Gateway Components Already Log to Standard Output +### Gateway components already log to standard output **No special configuration is required to enable logging in the gateway components.** All gateway components (gateway-controller, policy-engine, and router) follow the [12-factor app](https://12factor.net/logs) architecture principle for logging: @@ -50,13 +50,13 @@ The default logging stack consists of: This architecture approach allows you to utilize **any industry-standard logging stack** to collect logs from Docker container log files and view them in your preferred observability platform. The gateway components are completely decoupled from the logging infrastructure. -### Demonstrated Logging Services +### Demonstrated logging services The logging services included in the Docker Compose file (OpenSearch, OpenSearch Dashboards, and Fluent Bit) are provided as **demonstration services** to show one possible way to collect and visualize logs. You can use them as-is for development/testing, or replace them with your own logging solution. The gateway uses Docker Compose profiles to optionally enable these demonstration logging services. -### Start Gateway with Demonstrated Logging Services +### Start gateway with demonstrated logging services To start the gateway with the demonstration logging services enabled: @@ -70,7 +70,7 @@ This starts: - OpenSearch Dashboards - *web UI for viewing logs* - Fluent Bit - *collects logs from Docker and forwards to OpenSearch* -### Start Gateway without Logging Services +### Start gateway without logging services To run only the core gateway services without the demonstration logging stack: @@ -86,7 +86,7 @@ docker logs policy-engine docker logs router ``` -### Stop Logging Services +### Stop logging services To stop all services including the logging stack: @@ -102,7 +102,7 @@ docker compose --profile logging down -v This removes the `opensearch-data` volume containing all stored logs. -## Viewing Logs in OpenSearch Dashboards +## Viewing logs in OpenSearch Dashboards Once you've started the gateway with the logging profile, follow these steps to view component logs: @@ -113,7 +113,7 @@ Open your browser and navigate to: http://localhost:5601 ``` -### Step 2: Create an Index Pattern +### Step 2: Create an index pattern Before you can view logs, you need to create an index pattern: @@ -126,7 +126,7 @@ Before you can view logs, you need to create an index pattern: 7. Select **@timestamp** as the time field 8. Click **Create index pattern** -### Step 3: Navigate to Discover +### Step 3: Navigate to discover To view and explore logs: @@ -135,11 +135,11 @@ To view and explore logs: 3. Select the `gateway-logs-*` index pattern from the dropdown in the top-left 4. Adjust the time range in the top-right corner if needed (default is last 15 minutes) -### Step 4: Filter Logs by Component +### Step 4: Filter logs by component To view logs for a specific gateway component, use filters: -#### View Policy Engine Logs +#### View policy engine logs 1. Click **Add filter** (below the search bar) 2. **Field**: Select `component` @@ -147,7 +147,7 @@ To view logs for a specific gateway component, use filters: 4. **Value**: Enter `policy-engine` 5. Click **Save** -#### View Gateway Controller Logs +#### View gateway controller logs 1. Click **Add filter** 2. **Field**: `component` @@ -155,7 +155,7 @@ To view logs for a specific gateway component, use filters: 4. **Value**: `gateway-controller` 5. Click **Save** -#### View Router (Envoy) Logs +#### View router (envoy) logs 1. Click **Add filter** 2. **Field**: `component` @@ -163,11 +163,11 @@ To view logs for a specific gateway component, use filters: 4. **Value**: `router` 5. Click **Save** -### Step 5: Search and Filter Logs +### Step 5: Search and filter logs You can refine your log search using: -#### Free Text Search +#### Free text search Enter keywords in the search bar at the top: ``` error @@ -176,19 +176,19 @@ error Weather-API ``` -#### Filter by Log Level +#### Filter by log level 1. Click **Add filter** 2. **Field**: `level` 3. **Operator**: `is` 4. **Value**: `error` (or `info`, `warn`, `debug`) -#### Combine Multiple Filters +#### Combine multiple filters Add multiple filters to narrow down results. For example: - Component: `policy-engine` - Level: `error` - Time range: Last 1 hour -#### Example Search Queries +#### Example search queries Search for errors in the policy engine: ``` @@ -205,18 +205,18 @@ Search for slow requests (if duration field exists): duration_ms:>1000 ``` -### Step 6: Customize Log View +### Step 6: Customize log view -- **Add/Remove Columns**: Click the **gear icon** next to the field list to select which fields to display +- **Add/remove columns**: Click the **gear icon** next to the field list to select which fields to display - **Sort**: Click column headers to sort by that field -- **Expand Logs**: Click the **>** arrow next to any log entry to see full details in JSON format -- **Save Search**: Click **Save** in the top menu to save your filters and queries for later use +- **Expand logs**: Click the **>** arrow next to any log entry to see full details in JSON format +- **Save search**: Click **Save** in the top menu to save your filters and queries for later use -## Alternative Logging Stacks +## Alternative logging stacks While the default setup uses OpenSearch and Fluent Bit, you can integrate with other logging platforms: -### Elastic Stack (ELK) +### Elastic stack (ELK) Replace OpenSearch with the Elastic Stack: @@ -286,7 +286,7 @@ grafana: - loki ``` -### Cloud-Native Solutions +### Cloud-native solutions #### AWS CloudWatch @@ -339,7 +339,7 @@ Configure Fluent Bit to forward to Splunk HEC: ``` -## Additional Resources +## Additional resources - [Fluent Bit Documentation](https://docs.fluentbit.io/) - [OpenSearch Documentation](https://opensearch.org/docs/latest/) diff --git a/en/docs/ai-gateway/observability/tracing.md b/en/docs/ai-gateway/observability/tracing.md index ed754845..69ae4521 100644 --- a/en/docs/ai-gateway/observability/tracing.md +++ b/en/docs/ai-gateway/observability/tracing.md @@ -1,5 +1,5 @@ --- -title: "Gateway Tracing" +title: "Gateway tracing" description: "Configure distributed tracing for API Platform AI Gateway using OpenTelemetry and Jaeger, with support for cloud-native tracing backends." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/observability/tracing/ md_url: https://wso2.com/api-platform/docs/ai-gateway/observability/tracing.md @@ -12,7 +12,7 @@ last_updated: 2026-06-16 content_type: "how-to" --- -# Gateway Tracing +# Gateway tracing This guide explains how to implement and configure distributed tracing for the API Platform Gateway components. @@ -22,14 +22,14 @@ The default tracing services included in the Docker Compose configuration are ** **Important**: You are free to choose any tracing or observability strategy that suits your environment and requirements. The provided setup is just one of many possible configurations. -## Tracing Architecture +## Tracing architecture The default tracing stack consists of: - **OpenTelemetry (OTLP) Collector**: Receives, processes, and exports trace data from gateway components - **Jaeger**: Stores and visualizes distributed traces with a web UI for trace exploration and analysis -### How It Works +### How it works 1. Gateway components (gateway-controller, policy-engine, router) are configured to export traces via OTLP (OpenTelemetry Protocol) 2. Components send trace spans to the OpenTelemetry Collector via gRPC (port 4317) or HTTP (port 4318) @@ -37,22 +37,22 @@ The default tracing stack consists of: 4. The OTLP Collector forwards traces to Jaeger for storage and visualization 5. Users can view and analyze traces through the Jaeger UI -### What is Distributed Tracing? +### What is distributed tracing? Distributed tracing tracks a request as it flows through multiple components: - **Trace**: Represents the entire journey of a request through the system - **Span**: Represents a single operation within a trace (e.g., policy execution, upstream call) -- **Context Propagation**: Traces are correlated across components using trace IDs and span IDs in headers +- **Context propagation**: Traces are correlated across components using trace IDs and span IDs in headers -## Enabling Tracing +## Enabling tracing -### Configuration Required +### Configuration required You need to enable tracing in the gateway configuration file and point it to your OTLP collector endpoint. The tracing configuration is located in `gateway/configs/config.toml`: -#### Policy Engine Tracing Configuration +#### Policy engine tracing configuration ```toml [tracing] @@ -64,13 +64,13 @@ max_export_batch_size = 512 # Maximum spans per batch sampling_rate = 1.0 # Sample rate (1.0 = 100%, 0.5 = 50%) ``` -### Demonstrated Tracing Services +### Demonstrated tracing services The tracing services included in the Docker Compose file (Jaeger and OpenTelemetry Collector) are provided as **demonstration services** to show one possible way to collect and visualize traces. You can use them as-is for development/testing, or replace them with your own tracing solution. The gateway uses Docker Compose profiles to optionally enable these demonstration tracing services. -### Start Gateway with Demonstrated Tracing Services +### Start gateway with demonstrated tracing services To start the gateway with the demonstration tracing services enabled: @@ -83,7 +83,7 @@ This starts: - OpenTelemetry Collector - *receives and processes traces* - Jaeger - *stores and visualizes traces* -### Start Gateway without Tracing Services +### Start gateway without tracing services To run only the core gateway services without the demonstration tracing stack: @@ -93,7 +93,7 @@ docker compose up -d **Note:** If tracing is enabled in the configuration but the OTLP collector is not running, components will log warnings about failed trace exports. To completely disable tracing, set `enabled = false` in the configuration. -### Stop Tracing Services +### Stop tracing services To stop all services including the tracing stack: @@ -103,7 +103,7 @@ docker compose --profile tracing down **Note:** Jaeger stores traces in memory by default. Stopping the service will lose all trace data. For persistent storage, configure Jaeger with a backend database (see Jaeger documentation). -## Viewing Traces in Jaeger +## Viewing traces in Jaeger Once you've started the gateway with the tracing profile, follow these steps to view distributed traces: @@ -114,40 +114,40 @@ Open your browser and navigate to: http://localhost:16686 ``` -### Step 2: Search for Traces +### Step 2: Search for traces The Jaeger UI provides several ways to search for traces: -1. **Select a Service** from the dropdown: +1. **Select a service** from the dropdown: - `policy-engine` - View traces from the policy engine - `router` - View traces from the Envoy router -2. **Select an Operation** (optional): +2. **Select an operation** (optional): - Choose "all" to see all operations - Or select a specific operation (e.g., specific policy execution) -3. **Adjust Lookback Time Range**: +3. **Adjust lookback time range**: - Default: Last 1 hour - Options: 5m, 15m, 1h, 6h, 12h, 1d, 2d, Custom -4. **Add Filters** (optional): +4. **Add filters** (optional): - **Tags**: Filter by specific tag values (e.g., `http.status_code=500`) - - **Min/Max Duration**: Filter by trace duration - - **Limit Results**: Control number of traces returned (default: 20) + - **Min/max duration**: Filter by trace duration + - **Limit results**: Control number of traces returned (default: 20) 5. Click **Find Traces** -### Step 3: Analyze Trace Details +### Step 3: Analyze trace details Click on any trace in the results to view detailed information: -#### Trace Timeline +#### Trace timeline - **Visual timeline** showing all spans in the trace - **Duration bars** showing relative time spent in each operation - **Parent-child relationships** between spans - **Color coding** by service -#### Span Details +#### Span details Click on any span to see: - **Operation name**: What operation was performed - **Duration**: How long it took @@ -155,40 +155,40 @@ Click on any span to see: - **Logs**: Events logged during the span (errors, warnings, etc.) - **Process**: Service name, version, and host information -#### Common Use Cases +#### Common use cases -**Finding Slow Requests:** +**Finding slow requests:** 1. Set Min Duration filter (e.g., 1000ms) 2. Click Find Traces 3. Examine spans to identify bottlenecks -**Debugging Errors:** +**Debugging errors:** 1. Filter by tag: `error=true` or `http.status_code=500` 2. Click on error traces 3. Examine span logs and tags for error details -**Understanding Request Flow:** +**Understanding request flow:** 1. Search for a specific trace ID (from logs or headers) 2. View the complete request path through all components 3. Identify which component handled which part of the request -### Step 4: Trace Comparison +### Step 4: Trace comparison You can compare multiple traces to identify patterns: 1. Select multiple traces using checkboxes 2. Click **Compare Traces** button 3. View side-by-side comparison of trace structure and timings -### Step 5: Service Dependency Graph +### Step 5: Service dependency graph View how services interact: 1. Click **Dependencies** in the top navigation 2. Select time range 3. View graph showing service-to-service communication patterns -## Configuration Options +## Configuration options -### Adjusting Sampling Rate +### Adjusting sampling rate To reduce trace volume in high-traffic environments, adjust the sampling rate: @@ -206,7 +206,7 @@ Sampling strategies: **Note:** Lower sampling rates reduce overhead but may miss important traces. -### Custom Service Names +### Custom service names Customize service names for better identification: @@ -215,7 +215,7 @@ Customize service names for better identification: service_name = "policy-engine-prod-us-east-1" ``` -### Batch Configuration +### Batch configuration Optimize batch settings for your environment: @@ -228,7 +228,7 @@ max_export_batch_size = 1024 # Export up to 1024 spans per batch **Lower timeout**: Faster trace visibility, more network overhead **Higher timeout**: Better batching efficiency, slower trace visibility -## Alternative Tracing Backends +## Alternative tracing backends While the default setup uses Jaeger, the gateway components use OpenTelemetry and can export to any OTLP-compatible backend. @@ -258,12 +258,12 @@ service: exporters: [otlphttp] # Send to Moesif ``` -**Important Notes:** +**Important notes:** - The endpoint uses HTTPS (not HTTP) - Use the `otlphttp` exporter (not `otlp` which uses gRPC) - The `X-Moesif-Application-Id` header is required for authentication -#### Obtaining Your Moesif Application ID +#### Obtaining your Moesif application ID 1. Sign up for a Moesif account at [moesif.com](https://www.moesif.com) 2. Log in to your Moesif dashboard @@ -271,7 +271,7 @@ service: 4. Locate the **Collector Application ID** field 5. Copy your unique Application ID -#### Using Environment Variables +#### Using environment variables For better security, use environment variables for the Application ID: @@ -300,7 +300,7 @@ export MOESIF_APPLICATION_ID=your-moesif-application-id docker compose --profile tracing up -d ``` -#### Accessing Moesif Dashboard +#### Accessing Moesif dashboard After configuring and starting the gateway: @@ -310,16 +310,16 @@ After configuring and starting the gateway: 4. Use **Time Series** to analyze API usage trends 5. Set up **Alerts** for error rates, latency, or custom conditions -#### Moesif Features +#### Moesif features -- **API Analytics**: Request volume, response times, error rates -- **User Tracking**: Identify and track API users across requests -- **Error Analysis**: Detailed error tracking with request/response bodies -- **Behavioral Cohorts**: Group users by API usage patterns -- **Custom Dashboards**: Build visualizations for your specific KPIs +- **API analytics**: Request volume, response times, error rates +- **User tracking**: Identify and track API users across requests +- **Error analysis**: Detailed error tracking with request/response bodies +- **Behavioral cohorts**: Group users by API usage patterns +- **Custom dashboards**: Build visualizations for your specific KPIs - **Alerting**: Get notified of anomalies or threshold breaches -#### Sending to Both Jaeger and Moesif +#### Sending to both Jaeger and Moesif You can send traces to both Jaeger (for development) and Moesif (for analytics): @@ -406,7 +406,7 @@ tracing: endpoint: tempo:4317 ``` -### Cloud-Native Tracing Solutions +### Cloud-native tracing solutions #### AWS X-Ray @@ -516,7 +516,7 @@ exporters: lightstep-access-token: ${LIGHTSTEP_ACCESS_TOKEN} ``` -### Service Mesh Integration +### Service mesh integration If using a service mesh like Istio or Linkerd: @@ -547,7 +547,7 @@ The OTLP Collector configuration is located at: gateway/observability/otel-collector/config.yaml ``` -### Configuration Structure +### Configuration structure The configuration consists of three main sections: @@ -612,7 +612,7 @@ exporters: sampling_thereafter: 200 ``` -#### Service Pipeline +#### Service pipeline Connect receivers, processors, and exporters: ```yaml @@ -624,7 +624,7 @@ service: exporters: [otlp, debug] ``` -### Example: Multi-Backend Export +### Example: Multi-backend export Send traces to multiple backends simultaneously: @@ -652,7 +652,7 @@ service: exporters: [otlp/jaeger, otlp/tempo, datadog] ``` -### Example: Tail-Based Sampling +### Example: Tail-based sampling Keep all error traces but sample successful traces: @@ -674,7 +674,7 @@ processors: sampling_percentage: 10 ``` -## Trace Context Propagation +## Trace context propagation The gateway components automatically propagate trace context using standard W3C Trace Context headers: @@ -693,7 +693,7 @@ curl http://localhost:8080/weather/v1.0/us/seattle \ This allows you to trace requests across your entire system, including services before and after the gateway. -## Best Practices +## Best practices ### Development - Use 100% sampling rate (`sampling_rate: 1.0`) @@ -724,7 +724,7 @@ This allows you to trace requests across your entire system, including services - Use asynchronous trace export (default with OTLP) - Consider using tail-based sampling for high-volume environments -### Sampling Strategy +### Sampling strategy Choose sampling based on traffic volume: @@ -739,7 +739,7 @@ Choose sampling based on traffic volume: ## Troubleshooting -### Traces Not Appearing in Jaeger +### Traces not appearing in Jaeger **1. Verify tracing is enabled in configuration:** ```bash @@ -778,14 +778,14 @@ docker logs policy-engine | grep -i trace docker logs gateway-controller | grep -i trace ``` -### Traces Are Incomplete or Missing Spans +### Traces are incomplete or missing spans **1. Check sampling rate** - ensure it's not too low **2. Verify all components are configured** to export traces **3. Check for trace context propagation issues** - ensure headers are preserved **4. Look for timeout errors** in OTLP collector logs -### High Trace Export Overhead +### High trace export overhead **1. Reduce sampling rate:** ```toml @@ -802,13 +802,13 @@ max_export_batch_size = 2048 **3. Use tail-based sampling** in OTLP collector to sample only important traces -### Traces Have Incorrect Timing +### Traces have incorrect timing - **Ensure system clocks are synchronized** across all containers (use NTP) - **Check for clock skew** in trace timeline view - **Verify trace context propagation** is working correctly -### Cannot Access Jaeger UI +### Cannot access Jaeger UI **1. Verify Jaeger is running:** ```bash @@ -825,7 +825,7 @@ docker logs jaeger curl http://localhost:16686/ ``` -## Disabling Tracing +## Disabling tracing To completely disable tracing: @@ -847,15 +847,15 @@ docker compose restart gateway-controller policy-engine router **Note:** The router (Envoy) tracing is controlled by the gateway-controller configuration and will be disabled when the configuration is updated. -## Integration with Logging +## Integration with logging Traces and logs work together for comprehensive observability: -### Correlating Traces and Logs +### Correlating traces and logs -1. **Trace ID in Logs**: Gateway components include trace IDs in log entries -2. **Find Trace from Log**: Copy trace ID from log entry and search in Jaeger -3. **Find Logs from Trace**: Copy trace ID from Jaeger and search in log viewer +1. **Trace ID in logs**: Gateway components include trace IDs in log entries +2. **Find trace from log**: Copy trace ID from log entry and search in Jaeger +3. **Find logs from trace**: Copy trace ID from Jaeger and search in log viewer Example log entry with trace ID: ```json @@ -869,7 +869,7 @@ Example log entry with trace ID: } ``` -### Using Both Stacks +### Using both stacks Enable both logging and tracing profiles: @@ -881,7 +881,7 @@ This provides complete observability: - **Traces**: Request flow and performance - **Logs**: Detailed event information and debugging -## Additional Resources +## Additional resources - [OpenTelemetry Documentation](https://opentelemetry.io/docs/) - [Jaeger Documentation](https://www.jaegertracing.io/docs/) diff --git a/en/docs/ai-gateway/overview.md b/en/docs/ai-gateway/overview.md index 76fa77bf..05aa6d73 100644 --- a/en/docs/ai-gateway/overview.md +++ b/en/docs/ai-gateway/overview.md @@ -1,5 +1,5 @@ --- -title: "API Platform AI Gateway Overview" +title: "API Platform AI Gateway overview" description: "Manage and secure AI traffic with API Platform AI Gateway: LLM providers, LLM proxies, MCP proxies, and guardrails for LLM APIs and MCP servers." canonical_url: https://wso2.com/api-platform/docs/ai-gateway/overview/ md_url: https://wso2.com/api-platform/docs/ai-gateway/overview.md @@ -16,18 +16,18 @@ content_type: "concept" A gateway for managing and securing AI traffic, including Large Language Model (LLM) APIs and Model Context Protocol (MCP) servers. -## Quick Start +## Quick start - [LLM Quick Start Guide](llm-proxy/quick-start-guide.md) - Set up the gateway, verify the controller admin health endpoint, and route traffic to LLM providers like OpenAI - [MCP Quick Start Guide](mcp-proxy/quick-start-guide.md) - Set up the gateway, verify the controller admin health endpoint, and route traffic to MCP servers -## Key Concepts +## Key concepts -### LLM Provider Template +### LLM provider template An LLM Provider Template defines the characteristics and behaviors specific to an AI service provider, such as OpenAI, Azure OpenAI, or other LLM platforms. It describes how the gateway should interpret and extract usage and operational metadata, including prompt, completion, total, and remaining token information, as well as request and response model metadata. -Following templates are shipped out-of-the-box +The following templates are shipped out-of-the-box - OpenAI - Azure OpenAI @@ -36,7 +36,7 @@ Following templates are shipped out-of-the-box - Azure AI Foundry - Gemini -### LLM Provider +### LLM provider An LLM Provider represents a connection to an AI backend service such as OpenAI, Azure OpenAI, or other LLM APIs. Platform administrators configure LLM Providers to define: @@ -49,15 +49,15 @@ An LLM Provider represents a connection to an AI backend service such as OpenAI, Once configured, the LLM Provider allows traffic to flow through the gateway to the AI backend. -### LLM Proxy +### LLM proxy -An LLM Proxy allows developers to create custom API endpoints that consume an LLM Provider, while inheriting administrator-enforced access control, budgeting and organization-wide policies defined at the provider level. Each proxy gets its own URL context (e.g., `/assistant`) and can have its own policies applied. This enables: +An LLM Proxy allows developers to create custom API endpoints that consume an LLM Provider, while inheriting administrator-enforced access control, budgeting, and organization-wide policies defined at the provider level. Each proxy gets its own URL context (e.g., `/assistant`) and can have its own policies applied. This enables: - Multiple AI applications to share a single LLM Provider - Per-application policies such as prompt management and guardrails - Separation between platform administration and application development -### MCP Proxy +### MCP proxy An MCP Proxy routes Model Context Protocol traffic to MCP servers. MCP is a protocol that enables AI assistants to interact with external tools and data sources. With MCP Proxies, you can: @@ -65,7 +65,7 @@ An MCP Proxy routes Model Context Protocol traffic to MCP servers. MCP is a prot - Apply authentication and access control to MCP traffic - Manage multiple MCP servers from a single control plane -## Default Ports +## Default ports | Port | Service | Description | |------|---------|-------------| @@ -97,7 +97,7 @@ An MCP Proxy routes Model Context Protocol traffic to MCP servers. MCP is a prot 2. Developers create LLM Proxies to build AI applications on top of available providers 3. The gateway routes traffic, applies policies, and manages authentication -## AI Guardrails +## AI guardrails AI Guardrails allow you to enforce safety, content, and compliance policies on AI traffic flowing through the AI Gateway. They can be applied at the LLM Provider level (organization-wide), at the LLM Proxy level (per-application), or on MCP Proxies. diff --git a/en/docs/analytics-and-monetization/overview.md b/en/docs/analytics-and-monetization/overview.md index 098e4242..4d3c16ac 100644 --- a/en/docs/analytics-and-monetization/overview.md +++ b/en/docs/analytics-and-monetization/overview.md @@ -1,5 +1,5 @@ --- -title: "Analytics and Monetization with Moesif" +title: "Analytics and monetization with Moesif" description: "Use the Moesif integration in WSO2 API Platform for API analytics, usage-based billing, governance, and proactive monitoring of APIs and AI endpoints." canonical_url: https://wso2.com/api-platform/docs/analytics-and-monetization/overview/ md_url: https://wso2.com/api-platform/docs/analytics-and-monetization/overview.md @@ -12,7 +12,7 @@ last_updated: 2026-06-11 content_type: "concept" --- -# Analytics and Monetization with Moesif +# Analytics and monetization with Moesif To provide enterprise-grade observability and usage-based billing, WSO2 API Platform integrates directly with Moesif, a leading analytics and monetization platform for AI and API products. @@ -22,41 +22,41 @@ Visit [Moesif documentation](https://moesif.com/docs) to explore comprehensive s This page provides a high-level overview of what you can achieve with Moesif. -## Core Capabilities +## Core capabilities -Moesif extends your API platform with these primariy capabilities: +Moesif extends your API platform with these primary capabilities: -### API Analytics and Observability +### API analytics and observability Deeply understand customer API usage to improve your API strategy. -* **Usage and Body Analytics:** Track API logs, payloads, and metrics to see exactly which endpoints are heavily used and how they perform. -* **Customizable Dashboards:** Build customized views to track funnel metrics like Time to First Hello World, adoption rates, and drop-offs. -* **Customer Journey Tracking:** Correlate API traffic with website and portal interactions to observe the end-to-end user experience. +* **Usage and body analytics:** Track API logs, payloads, and metrics to see exactly which endpoints are heavily used and how they perform. +* **Customizable dashboards:** Build customized views to track funnel metrics like Time to First Hello World, adoption rates, and drop-offs. +* **Customer journey tracking:** Correlate API traffic with website and portal interactions to observe the end-to-end user experience. -### API Monetization and Metered Billing +### API monetization and metered billing Effortlessly turn your APIs and AI endpoints into revenue centers. -* **Usage-Based Billing:** Set up billing meters based on API calls, LLM token counts, or custom metrics. -* **Billing Provider Integrations:** Connect directly to payment gateways like Stripe, Recurly, Chargebee, or Zuora to automate invoicing and payments. -* **Product Catalogs:** Define pricing plans, tiers, and prepaid credits without writing custom billing code. +* **Usage-based billing:** Set up billing meters based on API calls, LLM token counts, or custom metrics. +* **Billing provider integrations:** Connect directly to payment gateways like Stripe, Recurly, Chargebee, or Zuora to automate invoicing and payments. +* **Product catalogs:** Define pricing plans, tiers, and prepaid credits without writing custom billing code. -### API Governance +### API governance Enforce contract terms and prevent API abuse dynamically. -* **Quotas and Limits:** Automatically enforce subscription quotas and block traffic when customers exceed limits. -* **Prepaid Credits:** Manage trial accounts, freemium tiers, and prepaid credit balances. +* **Quotas and limits:** Automatically enforce subscription quotas and block traffic when customers exceed limits. +* **Prepaid credits:** Manage trial accounts, freemium tiers, and prepaid credit balances. -### Proactive Monitoring and Alerting +### Proactive monitoring and alerting Guarantee customer success and reduce mean time to resolution (MTTR). -* **Behavioral Alerts:** Get notified when a key customer's API usage drops suddenly, indicating a potential churn risk or integration issue. -* **Error Tracking:** Dig into API traffic, headers, and traces to quickly resolve customer implementation issues. -* **Automated Emails:** Automatically guide developers at scale by sending behavioral emails—for example, when they near their quota limit or successfully make their first API call. +* **Behavioral alerts:** Get notified when a key customer's API usage drops suddenly, indicating a potential churn risk or integration issue. +* **Error tracking:** Dig into API traffic, headers, and traces to quickly resolve customer implementation issues. +* **Automated emails:** Automatically guide developers at scale by sending behavioral emails—for example, when they near their quota limit or successfully make their first API call. -### Developer Experience +### Developer experience Share insights directly with your API consumers. Use Embedded Metrics to expose usage metrics and quota dashboards directly inside Developer Portal so users can track their consumption in real time. -## Next Steps +## Next steps * [Visit Moesif documentation](https://www.moesif.com/docs/). * [Get familiar with Metered Billing](https://www.moesif.com/docs/metered-billing/). diff --git a/en/docs/api-gateway/analytics/analytics-header-filter.md b/en/docs/api-gateway/analytics/analytics-header-filter.md index 2cb2f905..58bcf3f4 100644 --- a/en/docs/api-gateway/analytics/analytics-header-filter.md +++ b/en/docs/api-gateway/analytics/analytics-header-filter.md @@ -1,5 +1,5 @@ --- -title: "Analytics Header Filter Policy" +title: "Analytics header filter policy" description: "Control which request and response headers are captured in analytics using allow or deny mode in API Platform Gateway." canonical_url: https://wso2.com/api-platform/docs/api-gateway/analytics/analytics-header-filter/ md_url: https://wso2.com/api-platform/docs/api-gateway/analytics/analytics-header-filter.md @@ -12,7 +12,7 @@ last_updated: 2026-06-17 content_type: "reference" --- -# Analytics Header Filter +# Analytics header filter ## Overview @@ -45,7 +45,7 @@ Request and response headers can have different operation modes, allowing for fl | `requestHeadersToFilter` | object | No | - | Configuration for filtering request headers. Contains `operation` and `headers` properties. | | `responseHeadersToFilter` | object | No | - | Configuration for filtering response headers. Contains `operation` and `headers` properties. | -### Parameter Structure +### Parameter structure Each filter parameter (`requestHeadersToFilter` and `responseHeadersToFilter`) is an object with the following properties: @@ -57,14 +57,14 @@ Each filter parameter (`requestHeadersToFilter` and `responseHeadersToFilter`) i > **Note**: This policy only affects analytics data collection. It does not remove or modify headers sent to upstream services or returned to clients. -## System Requirements +## System requirements * Analytics must be enabled globally via `config.yaml` (`analytics.enabled: true`) * The policy must be explicitly applied to the API policy chain * If analytics is disabled at the system level, this policy has no effect -## API Definition Example +## API definition example The following example demonstrates how to apply the Analytics Header Filter policy to a REST API: @@ -104,15 +104,15 @@ spec: EOF ``` -## Use Cases +## Use cases -- **Sensitive Data Protection**: Prevent authentication tokens, internal identifiers, or security-related headers from being sent to analytics systems. +- **Sensitive data protection**: Prevent authentication tokens, internal identifiers, or security-related headers from being sent to analytics systems. -- **Noise Reduction**: Exclude verbose or low-value headers to improve the clarity and usefulness of analytics data. +- **Noise reduction**: Exclude verbose or low-value headers to improve the clarity and usefulness of analytics data. -- **Compliance and Governance**: Support compliance requirements by ensuring certain headers are never exported outside the platform. +- **Compliance and governance**: Support compliance requirements by ensuring certain headers are never exported outside the platform. -- **Cost and Storage Optimization**: Reduce analytics payload size by removing unnecessary headers from published events. +- **Cost and storage optimization**: Reduce analytics payload size by removing unnecessary headers from published events. ## Notes diff --git a/en/docs/api-gateway/analytics/moesif-analytics.md b/en/docs/api-gateway/analytics/moesif-analytics.md index d534cb20..33e95bb2 100644 --- a/en/docs/api-gateway/analytics/moesif-analytics.md +++ b/en/docs/api-gateway/analytics/moesif-analytics.md @@ -1,5 +1,5 @@ --- -title: "Configure Moesif Analytics" +title: "Configure Moesif analytics" description: "Configure the Moesif in API Platform Gateway to capture and publish API request and response data." canonical_url: https://wso2.com/api-platform/docs/api-gateway/analytics/moesif-analytics/ md_url: https://wso2.com/api-platform/docs/api-gateway/analytics/moesif-analytics.md @@ -37,8 +37,8 @@ This capability allows platform administrators and business stakeholders to gain - Active Moesif Account and an Application ID. For obtaining the Application ID, follow these steps: - Step 1: Sign up in [Moesif](https://www.moesif.com/) - - Sept 2: Follow the onboarding wizard. - - Sept 3: During the sign up process, you will receive a Collector Application ID for your configured application. Copy this value and keep it saved. + - Step 2: Follow the onboarding wizard. + - Step 3: During the sign up process, you will receive a Collector Application ID for your configured application. Copy this value and keep it saved. !!! note For more detailed instructions and advanced configuration options, refer to the [official Moesif Documentation](https://www.moesif.com/docs). @@ -48,7 +48,7 @@ This capability allows platform administrators and business stakeholders to gain Analytics is configured entirely through the gateway `config.toml` file and is enabled at a system level. -### System Parameters (`config.toml`) +### System parameters (`config.toml`) #### Analytics @@ -64,7 +64,7 @@ Analytics is configured entirely through the gateway `config.toml` file and is e | `enabled` | boolean | Yes | Enables the publisher | | `settings` | object | Yes | Map of Publisher specific attributes required for configuring the publisher client | -#### gRPC Event Server +#### gRPC event server This section configures both the Envoy access log streaming settings and the ALS (Access Log Service) server that receives those logs. The ALS server runs within the policy-engine component. @@ -84,9 +84,9 @@ This section configures both the Envoy access log streaming settings and the ALS **Note:** The hostname for the ALS connection is automatically derived from the policy-engine configuration. The internal log name identifier is set to `"envoy_access_log"` and is not configurable. -## Configuration Examples +## Configuration examples -#### Integrate Moesif Publisher +#### Integrate Moesif publisher For Moesif analytics integration, the following publisher-specific attributes must be configured under the `settings` section. These parameters control authentication, batching behavior, and publish intervals for efficient analytics delivery. The required attributes are as follows. @@ -126,11 +126,11 @@ max_header_limit = 8192 ``` -## Use Cases +## Use cases -* **API Usage Visibility** – Understand how APIs are consumed across tenants and applications. -* **Operational Insights** – Observe traffic volume, response behavior, and latency trends. -* **Business Intelligence** – Support product and business decisions using API analytics data. -* **Platform Monitoring** – Gain observability into API behavior without impacting performance. +* **API usage visibility** – Understand how APIs are consumed across tenants and applications. +* **Operational insights** – Observe traffic volume, response behavior, and latency trends. +* **Business intelligence** – Support product and business decisions using API analytics data. +* **Platform monitoring** – Gain observability into API behavior without impacting performance. diff --git a/en/docs/api-gateway/deployment/deploying-apis/bottom-up-api-deployment.md b/en/docs/api-gateway/deployment/deploying-apis/bottom-up-api-deployment.md index 521b370b..7272284d 100644 --- a/en/docs/api-gateway/deployment/deploying-apis/bottom-up-api-deployment.md +++ b/en/docs/api-gateway/deployment/deploying-apis/bottom-up-api-deployment.md @@ -1,5 +1,5 @@ --- -title: "Bottom-Up API Deployment Guide" +title: "Bottom-up API deployment guide" description: "Deploy REST APIs directly to API Platform Gateway and automatically sync them to on-prem WSO2 API Manager using bottom-up deployment." canonical_url: https://wso2.com/api-platform/docs/api-gateway/deployment/deploying-apis/bottom-up-api-deployment/ md_url: https://wso2.com/api-platform/docs/api-gateway/deployment/deploying-apis/bottom-up-api-deployment.md @@ -12,17 +12,17 @@ last_updated: 2026-06-11 content_type: "how-to" --- -# Bottom-Up API Deployment Guide +# Bottom-up API deployment guide ## Overview When you deploy a REST API via the gateway controller's REST API endpoint, the gateway **automatically tracks it for bottom-up sync** to on-prem WSO2 APIM 4.7.x (if configured for on-prem control plane mode). -### Understanding API Deployment Approaches +### Understanding API deployment approaches The WSO2 API Platform gateway supports two fundamentally different deployment approaches, distinguished by the **direction of API flow**: -#### **Top-Down Deployment (Control Plane → Gateway)** +#### **Top-down deployment (control plane → gateway)** In top-down deployment, the **platform-API (central control plane) pushes APIs to the gateway** via WebSocket connection. @@ -32,7 +32,7 @@ In top-down deployment, the **platform-API (central control plane) pushes APIs t - Gateway receives and applies these definitions - Gateway pulls configuration from control plane -#### **Bottom-Up Deployment (Gateway → On-Prem APIM)** +#### **Bottom-up deployment (gateway → On-prem APIM)** Currently this support is only available for the on prem APIM control plane type. @@ -52,16 +52,16 @@ In bottom-up deployment, **REST APIs deployed directly to the gateway are automa - **Continues working:** API remains available on gateway even if APIM is unavailable -#### **Key Differences** +#### **Key differences** | Aspect | Top-Down | Bottom-Up | |--------|----------|-----------| | **Initiation** | Control plane (platform-API) | Gateway (REST API) | | **Direction** | Platform-API → Gateway | Gateway → On-Prem APIM | -| **Source of Truth** | Central control plane | Local gateway | -| **APIM Integration** | Not applicable | Syncs to on-prem APIM | -| **Status Tracking** | Managed by platform-API | Tracked in gateway DB | -| **Failure Handling** | Depends on platform-API | API works, sync retries | +| **Source of truth** | Central control plane | Local gateway | +| **APIM integration** | Not applicable | Syncs to on-prem APIM | +| **Status tracking** | Managed by platform-API | Tracked in gateway DB | +| **Failure handling** | Depends on platform-API | API works, sync retries | --- @@ -69,12 +69,12 @@ In bottom-up deployment, **REST APIs deployed directly to the gateway are automa ## Prerequisites -### Gateway Controller Requirements +### Gateway controller requirements - Gateway controller running locally or remotely - Management API endpoint: `http://localhost:9090/api/management/v0.9` (default) -### Bottom-Up API Sync Requirements +### Bottom-up API sync requirements - On-prem WSO2 APIM instance - Control plane configuration with on-prem mode enabled @@ -85,7 +85,7 @@ In bottom-up deployment, **REST APIs deployed directly to the gateway are automa ## Configuration -### Gateway Controller Configuration +### Gateway controller configuration **File:** `config.toml` @@ -121,9 +121,9 @@ roles = ["admin"] --- -## How It Works +## How it works -### Sync Behavior +### Sync behavior When you deploy a REST API via the gateway controller: @@ -138,7 +138,7 @@ When you deploy a REST API via the gateway controller: - Status tracked in database: `pending` → `success`/`failed` - Automatic retries (3 attempts) on failure -### Conditions for Sync +### Conditions for sync All three must be true: @@ -148,7 +148,7 @@ controlPlaneClient.IsConnected() && // WebSocket connected to APIM controlPlaneClient.IsOnPrem() // On-prem mode detected (via .well-known endpoint) ``` -### What Happens If Sync Fails +### What happens if sync fails - API **remains available on the gateway** - Status marked as `failed` with error details @@ -157,11 +157,11 @@ controlPlaneClient.IsOnPrem() // On-prem mode detected (via .well-known --- -## REST API Deployment +## REST API deployment Bottom-up APIs are REST APIs deployed via the gateway controller that are **automatically synced** to on-prem WSO2 APIM. -### Key Features +### Key features - All REST APIs deployed via gateway are tracked for bottom-up sync - Automatic sync to on-prem APIM (if connected) @@ -171,7 +171,7 @@ Bottom-up APIs are REST APIs deployed via the gateway controller that are **auto - Support for API updates and undeployment - Continues working even if APIM is temporarily unavailable -### Deployment Flow +### Deployment flow ``` ┌─────────────────────────────────────────────────┐ @@ -218,7 +218,7 @@ Bottom-up APIs are REST APIs deployed via the gateway controller that are **auto └────────────────┘ ``` -### API Definition +### API definition All REST APIs deployed via the gateway will be synced to on-prem APIM automatically. Here's a complete example: @@ -282,7 +282,7 @@ spec: path: / ``` -**Important Notes:** +**Important notes:** - `metadata.name` must be unique per API - `context` becomes the URL path prefix on the gateway @@ -290,7 +290,7 @@ spec: - `version` is tracked separately (can have multiple versions of same API) - Policies are optional but recommended for security -### Deployment Steps +### Deployment steps **Step 1: Create API YAML** @@ -388,9 +388,9 @@ curl -X GET https://192.168.0.102:9443/api/am/publisher/v4/apis \ --- -## API Updates +## API updates -### Automatic Re-Sync on Update +### Automatic re-sync on update When you update an API, it's automatically re-synced to on-prem APIM (if connected). @@ -436,14 +436,14 @@ curl -X PUT http://localhost:9090/api/management/v0.9/rest-apis/PetStoreAPI \ --data-binary @petstore-api-updated.yaml ``` -**What Happens:** +**What happens:** 1. API updated on gateway immediately 2. Sync status internally reset to `pending` 3. Automatically re-synced to on-prem APIM 4. Both gateway and APIM have the updated version -**Check Updated Status:** +**Check updated status:** Monitor gateway controller logs for the sync result: @@ -454,9 +454,9 @@ Monitor gateway controller logs for the sync result: --- -## API Undeploy +## API undeploy -### Undeploy from Gateway and APIM +### Undeploy from gateway and APIM To undeploy an API, send a DELETE request with the API name: @@ -476,9 +476,9 @@ curl -X DELETE http://localhost:9090/api/management/v0.9/rest-apis/PetStoreAPI \ --- -## API Management Operations +## API management operations -### Create API Key +### Create API key ```bash curl -X POST http://localhost:9090/api/management/v0.9/rest-apis/PetStoreAPI/api-keys \ @@ -499,21 +499,21 @@ curl -X POST http://localhost:9090/api/management/v0.9/rest-apis/PetStoreAPI/api } ``` -### Invoke Protected API +### Invoke protected API ```bash curl http://localhost:8080/petstore/pet/1 \ -H "X-API-Key: apip_39ec8f6b69ef0edaf090e11be4dbf6c379176c53cd9a86131ee3c1fc4df0a8ds" ``` -### List API Keys +### List API keys ```bash curl -X GET http://localhost:9090/api/management/v0.9/rest-apis/PetStoreAPI/api-keys \ -H "Authorization: Basic ${BASE64_CREDENTIALS}" ``` -### Revoke API Key +### Revoke API key ```bash curl -X DELETE http://localhost:9090/api/management/v0.9/rest-apis/PetStoreAPI/api-keys/key-uuid-12345 \ @@ -522,9 +522,9 @@ curl -X DELETE http://localhost:9090/api/management/v0.9/rest-apis/PetStoreAPI/a --- -## Sync Status Tracking +## Sync status tracking -### Understand Sync States +### Understand sync states The gateway tracks the APIM sync state internally in its database. You can monitor it via the gateway controller logs. @@ -535,7 +535,7 @@ The gateway tracks the APIM sync state internally in its database. You can monit | `failed` | Sync failed after 3 retries | `"Bottom-up sync: all retries exhausted"` | -### Retry Failed Sync +### Retry failed sync If sync fails, the gateway automatically retries up to 3 times per sync cycle. Sync is re-triggered on the next control plane reconnection, or immediately when you update the API. @@ -552,13 +552,13 @@ curl -X PUT http://localhost:9090/api/management/v0.9/rest-apis/PetStoreAPI \ ## Troubleshooting -### Issue: API Not Syncing to APIM +### Issue: API not syncing to APIM **Symptom:** Gateway logs show `"Bottom-up sync: attempt failed"` or `"Bottom-up sync: all retries exhausted"` **Possible Causes & Solutions:** -#### 1. Control Plane Not Configured +#### 1. Control plane not configured ```bash # Check if host is set @@ -573,7 +573,7 @@ export APIP_GW_CONTROLLER__CONTROLPLANE__APIM_OAUTH2__CLIENT_ID=... export APIP_GW_CONTROLLER__CONTROLPLANE__APIM_OAUTH2__CLIENT_SECRET=... ``` -#### 2. APIM Not Reachable +#### 2. APIM not reachable **Check connectivity:** @@ -590,7 +590,7 @@ curl -k https://192.168.0.102:9443/internal/gateway/.well-known - Check firewall rules - Verify HTTPS/TLS settings (`insecureSkipVerify` may be needed) -#### 3. Invalid OAuth2 Credentials +#### 3. Invalid OAuth2 credentials **Check APIM logs** for authentication errors @@ -599,7 +599,7 @@ curl -k https://192.168.0.102:9443/internal/gateway/.well-known - Ensure OAuth2 credentials have proper scopes: `apim:api_import_export apim:api_view` - Try alternative auth method (username/password instead of client credentials) -#### 4. Missing Upstream URL +#### 4. Missing upstream URL **Check API definition:** @@ -610,7 +610,7 @@ curl -X GET http://localhost:9090/api/management/v0.9/rest-apis/PetStoreAPI \ **Fix:** Ensure `upstream.main.url` is set to a valid backend service -#### 5. Gateway-Controller Not Connected to APIM +#### 5. Gateway-controller not connected to APIM **Check if gateway is connected:** @@ -631,14 +631,14 @@ export APIP_GW_LOG_LEVEL=debug --data-binary @api-definition.yaml ``` -**View Gateway Connection Status:** +**View Gateway connection status:** Check gateway controller logs for: - `"Connected to control plane"` - Connected to APIM - `"Failed to resolve gateway path"` - Can't reach APIM - `"Resolved WebSocket connect URL"` - On-prem mode detected -### Issue: "Access Token Not Found" +### Issue: "access token not found" **Cause:** APIM OAuth2 token endpoint returned invalid response @@ -651,7 +651,7 @@ Check gateway controller logs for: export APIP_GW_LOG_LEVEL=debug ``` -### Issue: "On-prem Control Plane Mode Not Enabled" +### Issue: "On-prem control plane mode not enabled" **Cause:** `IsOnPrem()` check is failing diff --git a/en/docs/api-gateway/deployment/deployment-modes/immutable-gateway.md b/en/docs/api-gateway/deployment/deployment-modes/immutable-gateway.md index 22300254..f025d4b2 100644 --- a/en/docs/api-gateway/deployment/deployment-modes/immutable-gateway.md +++ b/en/docs/api-gateway/deployment/deployment-modes/immutable-gateway.md @@ -1,5 +1,5 @@ --- -title: "Immutable Gateway" +title: "Immutable gateway" description: "Run API Platform Gateway in immutable mode, loading API configurations from files at startup for GitOps and immutable infrastructure workflows." canonical_url: https://wso2.com/api-platform/docs/api-gateway/deployment/deployment-modes/immutable-gateway/ md_url: https://wso2.com/api-platform/docs/api-gateway/deployment/deployment-modes/immutable-gateway.md @@ -12,7 +12,7 @@ last_updated: 2026-06-11 content_type: "how-to" --- -# Immutable Gateway (V4.0.0) +# Immutable gateway This guide explains how to run the API Platform Gateway in **immutable mode**, where API configurations are loaded from files at startup instead of being managed through the REST API. @@ -79,7 +79,7 @@ Artifact files support Go template expressions for injecting dynamic values. Tem Use `| redact` for sensitive values to hide them from config dumps. A `| default "value"` pipe is available for fallback values. See [Gateway Artifact Templating](../../setup/artifact-templating.md) for the full function reference. -### Sample: Reading List API +### Sample: Reading list API Save the following as `artifacts/reading-list-v1.yaml`: diff --git a/en/docs/api-gateway/deployment/deployment-modes/kubernetes/gateway-operator-management-crds.md b/en/docs/api-gateway/deployment/deployment-modes/kubernetes/gateway-operator-management-crds.md index 67e6eda3..145a554a 100644 --- a/en/docs/api-gateway/deployment/deployment-modes/kubernetes/gateway-operator-management-crds.md +++ b/en/docs/api-gateway/deployment/deployment-modes/kubernetes/gateway-operator-management-crds.md @@ -1,5 +1,5 @@ --- -title: "Gateway Operator Management CRDs" +title: "Gateway operator management CRDs" description: "Reference for management-API-backed Kubernetes CRDs in API Platform Gateway: LlmProvider, LlmProxy, Mcp, ApiKey, SubscriptionPlan, Subscription, and Certificate." canonical_url: https://wso2.com/api-platform/docs/api-gateway/deployment/deployment-modes/kubernetes/gateway-operator-management-crds/ md_url: https://wso2.com/api-platform/docs/api-gateway/deployment/deployment-modes/kubernetes/gateway-operator-management-crds.md @@ -13,7 +13,7 @@ last_updated: 2026-06-17 content_type: "reference" --- -# Gateway Operator — Management CRDs +# Gateway operator — management CRDs This document covers the optional management-API-backed custom resources supported by the Gateway Operator: `LlmProviderTemplate`, `LlmProvider`, `LlmProxy`, `Mcp`, `ApiKey`, `SubscriptionPlan`, `Subscription`, and `Certificate`. @@ -25,7 +25,7 @@ In addition to `RestApi`, the operator supports management-API-backed CRDs such These resources use the same gateway selection model as `RestApi` (labels + `APIGateway.spec.apiSelector`). -## Shared Prerequisites +## Shared prerequisites Create a Kubernetes Secret containing credentials and tokens used by policy parameters and resource configurations: @@ -52,7 +52,7 @@ kubectl get secret httproute-demo-policy-credentials **Note:** The operator uses Kubernetes-native `valueFrom.secretKeyRef` references in policy parameters and resource configurations, allowing dynamic secret resolution at reconciliation time. This approach provides better security and follows Kubernetes best practices for secret management. -### Deploy LLM Backend Mock (Prerequisites for LLM Flow) +### Deploy LLM backend mock (prerequisites for LLM flow) The LLM resources require a mock OpenAI-compatible backend (Prism + nginx HTTPS). The manifest deploys to `apigateway-demo` by default; override to `default` namespace with: @@ -66,7 +66,7 @@ kubectl get deploy,svc -n default -l 'app.kubernetes.io/name in (mock-openai,moc Wait for both Deployments to be `Ready` before proceeding. -### Deploy ApiKey Resources (Prerequisites) +### Deploy apikey resources (prerequisites) Apply `ApiKey` CRs up front. The LLM-parent ApiKeys (`demo-llmprovider-apikey`, `demo-llmproxy-apikey`) will retry reconciliation automatically once their parent `LlmProvider`/`LlmProxy` are created. @@ -223,7 +223,7 @@ kubectl get llmprovidertemplate,llmprovider,llmproxy - Upstream authentication credentials can be sourced from Kubernetes Secrets via `valueFrom`. - The operator resolves all `valueFrom` references before sending the configuration to the gateway. -### Sample LLM API-key Protected Invocations +### Sample LLM API-key protected invocations ```bash # LlmProvider API-key protected (wrong key -> reject) @@ -262,7 +262,7 @@ curl -sS -k \ ## Deploy MCP -### Deploy MCP Backend (Prerequisites for MCP Flow) +### Deploy MCP backend (prerequisites for MCP flow) The MCP resources require the `mcp-server-backend` service. The manifest deploys to `apigateway-demo` by default; override to `default` namespace with: @@ -301,7 +301,7 @@ EOF kubectl get mcp ``` -### Sample MCP Client Invocations +### Sample MCP client invocations ```bash # 1) MCP initialize (capture headers to extract mcp-session-id) @@ -345,7 +345,7 @@ curl -sS -k \ Expected result: initialize returns success JSON-RPC response; `tools/call` returns `result.content[0].text` containing `The sum of 40 and 60 is 100.` -## Deploy RestAPI with Policy Parameter from Secret +## Deploy restapi with policy parameter from secret ```sh kubectl apply -f - <<'EOF' @@ -415,7 +415,7 @@ curl --request GET \ - Nested fields within policy parameters are automatically traversed and resolved. - The resolved string value replaces the `valueFrom` object before the API configuration is sent to the gateway. -## Deploy Hello Backend (Prerequisites for RestAPI Flows) +## Deploy hello backend (prerequisites for restapi flows) The RestAPI resources route to the `hello-backend` service. The manifest deploys to `apigateway-demo` by default; override to `default` namespace with: @@ -429,7 +429,7 @@ kubectl get deploy,svc -n default Wait for the Deployment to be `Ready` before proceeding. -## Deploy RESTAPI with API Key +## Deploy RestAPI with API key ```sh kubectl apply -f - <<'EOF' @@ -497,7 +497,7 @@ curl --request GET \ -k ``` -## Deploy REST API with Subscriptions +## Deploy REST API with subscriptions ```sh kubectl apply -f - <<'EOF' @@ -583,17 +583,17 @@ curl --request GET \ -k ``` -## Validation Notes +## Validation notes - `Subscription.spec.subscriptionPlanId` can be a literal ID or a `SubscriptionPlan` CR name. - `ApiKey.spec.parentRef.kind` supports `RestApi`, `LlmProvider`, and `LlmProxy`. - `ApiKey.spec.expiresAt` and `ApiKey.spec.expiresIn` are mutually exclusive (CEL validation rejects both together). -## valueFrom Pattern — Kubernetes-Native Secret Resolution +## valueFrom pattern — Kubernetes-native secret resolution The operator supports Kubernetes-native secret management through the `valueFrom` pattern, allowing policy parameters, credentials, and sensitive values to be resolved from Kubernetes Secrets at reconciliation time. -### Supported Use Cases +### Supported use cases The `valueFrom` pattern is supported in: @@ -610,11 +610,11 @@ The `valueFrom` pattern is supported in: 4. **Subscription tokens** in Subscription CRs - Authentication tokens resolved from Secrets -### Pattern Syntax +### Pattern syntax The `valueFrom` pattern supports two variants depending on the resource type: -**Variant 1: Policy Parameters** (RestApi, LlmProvider, LlmProxy) +**Variant 1: Policy parameters** (RestApi, LlmProvider, LlmProxy) Policy parameters use `valueFrom.secretKeyRef` for nested secret references: ```yaml @@ -626,7 +626,7 @@ params: key: subscription-key ``` -**Variant 2: Direct Fields** (ApiKey, Subscription, Upstream Auth) +**Variant 2: Direct fields** (ApiKey, Subscription, Upstream Auth) Resource-level secrets use `valueFrom` directly with `name` and `key`: ```yaml @@ -641,7 +641,7 @@ apiKey: - `key`: Required. The data key within the Secret. - `namespace`: Optional. Defaults to the CR's namespace. -### How It Works +### How it works 1. Operator watches all Kubernetes `Secret` resources in the namespace. 2. At reconciliation, operator fetches referenced Secret and extracts the value. @@ -649,11 +649,11 @@ apiKey: 4. Configuration is sent to gateway-controller with resolved values only. 5. If Secret is missing, reconciliation retries automatically. -### Change Detection +### Change detection The operator computes a fingerprint of all referenced Secret `resourceVersion` fields. When a Secret changes, affected CRs are automatically re-reconciled, ensuring credentials stay synchronized without manual intervention. -### Example: RestApi with Policy Parameter from Secret +### Example: RestAPI with policy parameter from secret Create the Secret: ```yaml @@ -700,7 +700,7 @@ policies: Update the Secret anytime; the operator automatically redeploys with the new value. -### Example 2: ApiKey with Direct valueFrom +### Example 2: API key with direct valuefrom Reference in ApiKey (using `name` and `key` directly): ```yaml @@ -721,6 +721,6 @@ spec: unit: days ``` -**Key Difference:** +**Key difference:** - RestApi policy params use nested `secretKeyRef` structure - ApiKey, Subscription, and upstream auth use flat `name`/`key` under `valueFrom` diff --git a/en/docs/api-gateway/deployment/deployment-modes/kubernetes/gateway-operator.md b/en/docs/api-gateway/deployment/deployment-modes/kubernetes/gateway-operator.md index 3c7cfb11..5adc22ac 100644 --- a/en/docs/api-gateway/deployment/deployment-modes/kubernetes/gateway-operator.md +++ b/en/docs/api-gateway/deployment/deployment-modes/kubernetes/gateway-operator.md @@ -1,5 +1,5 @@ --- -title: "Deploy with the Kubernetes Gateway Operator" +title: "Deploy with the Kubernetes gateway operator" description: "Deploy API Platform Gateway on Kubernetes using the operator with APIGateway and RestApi CRDs, or using the standard Kubernetes Gateway API with HTTPRoute." canonical_url: https://wso2.com/api-platform/docs/api-gateway/deployment/deployment-modes/kubernetes/gateway-operator/ md_url: https://wso2.com/api-platform/docs/api-gateway/deployment/deployment-modes/kubernetes/gateway-operator.md @@ -13,7 +13,7 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# Kubernetes Operator for API Platform Gateway +# Kubernetes operator for API Platform gateway The WSO2 API Platform Gateway Operator enables native Kubernetes deployment using a GitOps-friendly, operator-based model. It manages the full lifecycle of API gateways and REST APIs. You can use **either** platform CRDs **or** the **Kubernetes Gateway API** on the same operator build. @@ -27,7 +27,7 @@ For mode comparison and overall context, see [API Platform Kubernetes Gateway ov ## Overview -### Path A — Platform CRDs (`APIGateway` + `RestApi`) +### Path A — platform CRDs (`APIGateway` + `RestAPI`) | CRD | Purpose | |-----|---------| @@ -56,7 +56,7 @@ The operator watches these CRs, runs Helm for the gateway runtime, and deploys A ## Installation -### 1. Install Cert-Manager +### 1. Install Cert-manager The operator requires cert-manager for TLS certificate management: @@ -70,7 +70,7 @@ helm install cert-manager jetstack/cert-manager \ --set crds.enabled=true ``` -### 2. Install Gateway Operator +### 2. Install gateway operator ```sh helm install my-gateway-operator oci://ghcr.io/wso2/api-platform/helm-charts/gateway-operator --version 0.8.0 --set image.tag=0.8.1 @@ -203,7 +203,7 @@ curl --request GET \ --header 'Accept: application/json' -k ``` -## Management CRDs (LLM, MCP, API Key, Subscription) +## Management CRDs (LLM, MCP, API key, subscription) For complete documentation on optional management-API-backed CRDs (`LlmProviderTemplate`, `LlmProvider`, `LlmProxy`, `Mcp`, `ApiKey`, `SubscriptionPlan`, `Subscription`, `Certificate`), see [gateway-operator-management-crds.md](./gateway-operator-management-crds.md). @@ -217,7 +217,7 @@ That guide covers: - valueFrom pattern for Kubernetes-native secret resolution - Complete sample invocations and test endpoints -## Kubernetes Gateway API path +## Kubernetes gateway API path Use this when you prefer standard Gateway API resources instead of `APIGateway` / `RestApi`. The manifests below match the **`gateway-api-demo`** demo in this repository (`kubernetes/helm/resources/gateway-api-operator-demo/`). Apply them **in order**, or concatenate and `kubectl apply -f -`. @@ -304,7 +304,7 @@ EOF kubectl get gateway -n gateway-api-demo ``` -### 4. Sample backend (Deployment + Service) +### 4. Sample backend (deployment + service) ```sh kubectl apply -f - <<'EOF' @@ -415,7 +415,7 @@ curl --request GET \ -k ``` -### 6. Optional: second HTTPRoute (`hello-api-2`) +### 6. Optional: Second HTTPRoute (`hello-api-2`) ```sh kubectl apply -f - <<'EOF' @@ -467,11 +467,11 @@ Verify: `kubectl get gateway,httproute -n gateway-api-demo`, wait for parent con Common annotations on `HTTPRoute` are copied into the **`api.yaml`** payload (for example **`gateway.api-platform.wso2.com/context`**, **`api-version`**, **`api-handle`**, **`display-name`**, **`project-id`**). If **`context`** is omitted or only whitespace, it defaults to **`/`**. If a rule **`match`** omits **`method`**, the operator emits all RestApi-supported verbs for that path: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. -### Mixed clusters (`RestApi` + `Gateway`) +### Mixed clusters (`restapi` + `gateway`) If you run **both** `APIGateway`-selected **`RestApi`** resources and **Gateway API** routes, keep the **`gateway.api-platform.wso2.com/api-selector`** annotation on the **`Gateway`** (as in the YAML above) so this gateway does not select `RestApi` CRs meant for another `APIGateway`. -### Test API Endpoints +### Test API endpoints **Kubernetes Gateway API** — HTTPRoute **`hello-api`** from [above](#5-httproute-hello-api): API **`context`** `/hello-context`, route match path prefix **`/hello`** (hits Envoy HTTPS on the forwarded router port): @@ -484,7 +484,7 @@ curl --request GET \ Use **`NS=gateway-api-demo`** in the port-forward snippet when testing that demo. The sample backend may respond with a short plain-text body (e.g. `hello from gateway api demo`) depending on chart and image version. -### 7. HTTPRoute with Policies (APIPolicy CR) +### 7. HTTPRoute with policies (apipolicy CR) Attach policies to HTTPRoutes using the `APIPolicy` CR (`gateway.api-platform.wso2.com/v1alpha1`). Two attachment modes: @@ -711,18 +711,18 @@ kubectl patch secret httproute-demo-policy-credentials -n gateway-api-demo \ ``` -## Adding Backend Certificates +## Adding backend certificates For APIs connecting to backends with self-signed certificates: -### 1. Download the Certificate +### 1. Download the certificate ```sh curl -X GET "https://raw.githubusercontent.com/wso2/api-platform/refs/heads/main/gateway/resources/secure-backend/test-backend-certs/test-backend.crt" \ -o /tmp/test-backend.crt ``` -### 2. Add Certificate to Gateway +### 2. Add certificate to gateway ```sh cert_path="/tmp/test-backend.crt" @@ -731,7 +731,7 @@ curl -X POST http://localhost:9090/api/management/v0.9/certificates -u "admin:ad -d "{\"certificate\":$(jq -Rs . < $cert_path),\"filename\":\"my-cert.pem\", \"name\":\"test\"}" ``` -## Custom Configuration +## Custom configuration Per-gateway Helm values are supplied as a **ConfigMap** whose data includes **`values.yaml`** (partial YAML is fine; the operator **deep-merges** it onto the operator’s default gateway values file loaded from **`gateway.helm.valuesFilePath`**). @@ -807,7 +807,7 @@ The operator reads **`metadata.annotations[gateway.api-platform.wso2.com/helm-va - **CRD path:** `APIGateway` drives Helm; `RestApi` drives management REST deploys. - **Gateway API path:** `Gateway` drives the same Helm install pattern; `HTTPRoute` is translated to the same management REST payload shape as `RestApi`. -## Default Ports +## Default ports | Port | Component | Description | |------|-----------|-------------| @@ -819,7 +819,7 @@ The operator reads **`metadata.annotations[gateway.api-platform.wso2.com/helm-va | 9901 | Router | Envoy admin | | 9001 | Policy Engine | ext_proc gRPC | -## See Also +## See also - [Gateway Quick Start (Docker Compose)](../../../quick-start-guide.md) - [Policies](../../../overview.md#policies) diff --git a/en/docs/api-gateway/deployment/deployment-modes/kubernetes/kubernetes-standalone.md b/en/docs/api-gateway/deployment/deployment-modes/kubernetes/kubernetes-standalone.md index 127eaca7..e402cd97 100644 --- a/en/docs/api-gateway/deployment/deployment-modes/kubernetes/kubernetes-standalone.md +++ b/en/docs/api-gateway/deployment/deployment-modes/kubernetes/kubernetes-standalone.md @@ -1,5 +1,5 @@ --- -title: "Deploy in Kubernetes Standalone Mode" +title: "Deploy in Kubernetes standalone mode" description: "Install and manage API Platform Gateway on Kubernetes using the standalone Helm chart, without the Gateway Operator." canonical_url: https://wso2.com/api-platform/docs/api-gateway/deployment/deployment-modes/kubernetes/kubernetes-standalone/ md_url: https://wso2.com/api-platform/docs/api-gateway/deployment/deployment-modes/kubernetes/kubernetes-standalone.md @@ -13,7 +13,7 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# API Platform Gateway - Kubernetes Standalone Mode +# API Platform gateway - Kubernetes standalone mode This guide explains how to run API Platform Gateway in **Standalone Mode** using the gateway Helm chart only (without the Gateway Operator). @@ -25,7 +25,7 @@ Standalone mode is recommended when you want: For mode selection and architecture context, see [API Platform Kubernetes Gateway deployment modes](./overview.md). -## What Gets Deployed +## What gets deployed The gateway chart deploys the runtime components used by API Platform Gateway (controller and gateway runtime workloads) from chart templates and values. @@ -59,7 +59,7 @@ Verify: kubectl get pods -n cert-manager ``` -## Install Gateway Chart +## Install gateway chart Use one of the following patterns. @@ -97,7 +97,7 @@ helm install ap-gateway oci://ghcr.io/wso2/api-platform/helm-charts/gateway \ -f custom-values.yaml ``` -## Verify Installation +## Verify installation ```bash helm status ap-gateway @@ -114,7 +114,7 @@ kubectl logs -l app.kubernetes.io/component=controller kubectl logs -l app.kubernetes.io/component=gateway-runtime ``` -## Upgrade and Uninstall +## Upgrade and uninstall Upgrade: @@ -134,7 +134,7 @@ Namespace-scoped uninstall: helm uninstall ap-gateway --namespace api-gateway ``` -## Core Configuration Areas +## Core configuration areas Most runtime configuration is controlled in `values.yaml`. Common sections: @@ -149,9 +149,9 @@ Most runtime configuration is controlled in `values.yaml`. Common sections: Refer to inline comments in chart `values.yaml` for all supported fields. -## TLS Configuration +## TLS configuration -### Option 1: cert-manager (recommended) +### Option 1: Cert-manager (recommended) ```bash helm install ap-gateway oci://ghcr.io/wso2/api-platform/helm-charts/gateway \ @@ -190,7 +190,7 @@ helm install ap-gateway oci://ghcr.io/wso2/api-platform/helm-charts/gateway \ --set gateway.controller.tls.secret.name=gateway-tls ``` -## Upstream Custom CAs +## Upstream custom CAs When calling upstream services that use private/self-signed CAs: @@ -204,9 +204,9 @@ helm install ap-gateway oci://ghcr.io/wso2/api-platform/helm-charts/gateway \ --set gateway.controller.upstreamCerts.secretName=upstream-ca-certs ``` -## Create and Invoke API +## Create and invoke API -### Port-forward Gateway Controller Service +### Port-forward gateway controller service ```bash kubectl port-forward svc/ap-gateway-controller 9090:9090 @@ -267,7 +267,7 @@ curl http://localhost:8080/reading-list/v1.0/books curl -k https://localhost:8443/reading-list/v1.0/books ``` -## Next Steps +## Next steps - For operator-managed lifecycle and CRDs, see [Kubernetes Operator deployment mode](./gateway-operator.md). - For mode comparison and migration context from Kubernetes Gateway 1.3.0, see the [deployment modes overview page](./overview.md). \ No newline at end of file diff --git a/en/docs/api-gateway/deployment/deployment-modes/kubernetes/overview.md b/en/docs/api-gateway/deployment/deployment-modes/kubernetes/overview.md index 75110b36..62002a64 100644 --- a/en/docs/api-gateway/deployment/deployment-modes/kubernetes/overview.md +++ b/en/docs/api-gateway/deployment/deployment-modes/kubernetes/overview.md @@ -1,6 +1,6 @@ --- -title: "API Platform Kubernetes Gateway (V2.0.0)" -description: "Overview of API Platform Kubernetes Gateway V2.0.0 deployment modes: standalone, operator-managed, and Kubernetes Gateway API workflows." +title: "API Platform Kubernetes gateway (v2.0.0)" +description: "Overview of API Platform Kubernetes Gateway v2.0.0 deployment modes: standalone, operator-managed, and Kubernetes Gateway API workflows." canonical_url: https://wso2.com/api-platform/docs/api-gateway/deployment/deployment-modes/kubernetes/overview/ md_url: https://wso2.com/api-platform/docs/api-gateway/deployment/deployment-modes/kubernetes/overview.md tags: @@ -12,15 +12,15 @@ last_updated: 2026-06-19 content_type: "overview" --- -# API Platform Kubernetes Gateway (V2.0.0) +# API Platform Kubernetes gateway (v2.0.0) API Platform Gateway is the latest evolution of the WSO2 Kubernetes gateway experience. If you are coming from WSO2 Kubernetes gateway `1.3.0`, treat this as the successor track with a broader API Platform integration model and improved Kubernetes-native workflows. - Previous generation (reference): [WSO2 APK 1.3.0 docs](https://apk.docs.wso2.com/en/latest/) -- Current generation: API Platform Kubernetes Gateway V2.0.0 (this documentation set) +- Current generation: API Platform Kubernetes Gateway v2.0.0 (this documentation set) -## What Is New in V2.0.0 +## What is new in v2.0.0 - Unified API Platform gateway model for both standalone and operator-driven deployments. - Native support for Kubernetes Operator workflows and GitOps-style resource management. @@ -29,11 +29,11 @@ If you are coming from WSO2 Kubernetes gateway `1.3.0`, treat this as the succes - Kubernetes Gateway API (`GatewayClass`, `Gateway`, `HTTPRoute`, optional `APIPolicy`) - Improved extensibility for policies and secret/config-based parameter references. -## Deployment Modes +## Deployment modes Choose one of the following modes based on your operational model. -### 1) Kubernetes Standalone Mode +### 1) Kubernetes standalone mode Use this mode when you only need the gateway runtime and manage it directly via the gateway Helm chart. @@ -41,7 +41,7 @@ Use this mode when you only need the gateway runtime and manage it directly via - Best for simpler setups or environments where operator lifecycle management is not required. - Guide: [`kubernetes-standalone.md`](./kubernetes-standalone.md) -### 2) Kubernetes Operator Mode +### 2) Kubernetes operator mode Use this mode when you want operator-managed lifecycle, declarative resources, and automation. @@ -51,19 +51,19 @@ Use this mode when you want operator-managed lifecycle, declarative resources, a - Kubernetes Gateway API path (`Gateway` + `HTTPRoute`) - Guide: [`gateway-operator.md`](./gateway-operator.md) -## How to Choose a Mode +## How to choose a mode -- Choose **Standalone Mode** if your priority is a lightweight gateway runtime install with Helm-managed values. -- Choose **Operator Mode** if your priority is Kubernetes-native reconciliation, GitOps workflows, multi-resource lifecycle automation, and CRD-based API management. +- Choose **standalone mode** if your priority is a lightweight gateway runtime install with Helm-managed values. +- Choose **operator mode** if your priority is Kubernetes-native reconciliation, GitOps workflows, multi-resource lifecycle automation, and CRD-based API management. -## Policy Configuration +## Policy configuration -API Platform Kubernetes Gateway V2.0.0 supports attaching policies to APIs deployed in either mode. Policies control request/response mediation, rate limiting, authentication, and other gateway behaviors. +API Platform Kubernetes Gateway v2.0.0 supports attaching policies to APIs deployed in either mode. Policies control request/response mediation, rate limiting, authentication, and other gateway behaviors. For a full reference on available policies and how to configure them, see [Policy Configuration Overview](https://wso2.com/api-platform/docs/api-gateway/policies/overview/). -## Next Steps +## Next steps Learn more about the deployment modes: - [Standalone mode](./kubernetes-standalone.md) diff --git a/en/docs/api-gateway/deployment/high-availability-production-deployment.md b/en/docs/api-gateway/deployment/high-availability-production-deployment.md index ae54a219..cfab8488 100644 --- a/en/docs/api-gateway/deployment/high-availability-production-deployment.md +++ b/en/docs/api-gateway/deployment/high-availability-production-deployment.md @@ -1,5 +1,5 @@ --- -title: "High-Availability Production Deployment" +title: "High-availability production deployment" description: "Deploy API Platform Gateway in a highly available, production-grade configuration on Kubernetes with Helm, PostgreSQL, and replicated workloads." canonical_url: https://wso2.com/api-platform/docs/api-gateway/deployment/high-availability-production-deployment/ md_url: https://wso2.com/api-platform/docs/api-gateway/deployment/high-availability-production-deployment.md @@ -13,7 +13,7 @@ last_updated: 2026-06-11 content_type: "how-to" --- -# High-Availability Production Deployment +# High-availability production deployment This guide covers deploying the API Platform Gateway in a production-grade, highly available configuration using Helm on Kubernetes. Development mode is disabled, security is hardened, PostgreSQL backs the deployment state, and workloads are replicated across nodes. @@ -43,7 +43,7 @@ kubectl get nodes helm version ``` -## Cluster Topology +## Cluster topology Use at least two worker nodes for high availability. The recommended minimum production topology separates system and gateway workloads into dedicated node pools: @@ -68,7 +68,7 @@ This ensures that all Gateway Controller replicas operate with a consistent depl ![High-availability setup example](../../assets/img/api-platform-gateway/gateway/high-availability-architecture.png) -### Architecture Overview +### Architecture overview The deployment consists of the following main components: @@ -78,7 +78,7 @@ The deployment consists of the following main components: | **PostgreSQL Database** | Acts as the shared source of truth for API metadata, deployment state, and gateway configuration. | | **Gateway Runtime** | Receives configuration from its connected Gateway Controller and enforces API gateway policies at runtime. | -### Deployment Synchronization Flow +### Deployment synchronization flow When an API deployment request is received, it is handled by one of the available Gateway Controller replicas. @@ -90,7 +90,7 @@ Each Gateway Runtime then applies the received configuration and starts serving Each Gateway Controller replica can manage one or more Gateway Runtime replicas. -### High Availability Behavior +### High availability behavior High availability is achieved by removing dependency on a single controller instance. @@ -102,13 +102,13 @@ If one Gateway Controller replica becomes unavailable, another replica can conti Similarly, multiple Gateway Runtime replicas can be deployed in each environment to ensure API traffic continues to be served even if one runtime replica becomes unavailable. -### Configuration Synchronization +### Configuration synchronization The PostgreSQL database is the central synchronization point between Gateway Controller replicas. It maintains the latest API deployment state and allows all controller replicas to operate consistently. Gateway Runtime replicas do not directly read from the database. Instead, they receive the required runtime configuration from their connected Gateway Controller. This keeps the runtime layer lightweight and allows the controller layer to manage configuration generation and synchronization. -### Ingress Configuration +### Ingress configuration The Helm chart deploys Kubernetes `Service` objects for the Gateway Runtime and the Controller REST API, but does not provision an Ingress Controller or Ingress resources. You are responsible for configuring external access to these services using the ingress solution of your choice. @@ -116,9 +116,9 @@ At a minimum, expose the Gateway Runtime service on port **8443** (HTTPS) to rou If you are using the [bottom-up deployment](./deploying-apis/bottom-up-api-deployment.md) approach or running the gateway in standalone mode, also expose the Controller REST API service on port **9090** so that developers can deploy APIs directly to the gateway. -## Before You Begin +## Before you begin -### Start with the Base Values File +### Start with the base values file Download the default `values.yaml` for the gateway Helm chart and use it as the starting point for your production configuration. All steps in this guide reference fields within this file. @@ -126,7 +126,7 @@ Download the default `values.yaml` for the gateway Helm chart and use it as the curl -o values.yaml https://raw.githubusercontent.com/wso2/api-platform/refs/tags/gateway/v1.1.0/kubernetes/helm/gateway-helm-chart/values.yaml ``` -### Pin the Image Versions +### Pin the image versions Before making any other changes, set the controller and runtime image tags to the release you want to deploy. The latest stable release is **1.1.0**. @@ -151,7 +151,7 @@ gateway: The 4th digit represents **patch-level (U2) updates**, which include the latest fixes and security updates delivered through the WSO2 private registry. See [WSO2 Subscription Users](#wso2-subscription-users) below for registry configuration. -### WSO2 Subscription Users +### WSO2 subscription users If you have a WSO2 Subscription, images are pulled from the WSO2 private registry (`registry.wso2.com`) instead of the public GHCR registry. A single Helm field activates this mode end-to-end. @@ -187,7 +187,7 @@ Any explicit `image.repository` override (for example, pointing to an internal m When `wso2.subscription.imagePullSecret` is empty (the default), the chart renders identically to a non-subscription install and pulls from the public GHCR registry with no `imagePullSecrets` block. -## Setup Steps +## Setup steps Complete the following steps to configure a production-ready deployment: diff --git a/en/docs/api-gateway/deployment/production-deployment/control-plane-connection.md b/en/docs/api-gateway/deployment/production-deployment/control-plane-connection.md index f3559d16..3dc75d1b 100644 --- a/en/docs/api-gateway/deployment/production-deployment/control-plane-connection.md +++ b/en/docs/api-gateway/deployment/production-deployment/control-plane-connection.md @@ -1,5 +1,5 @@ --- -title: "Control Plane Connection" +title: "Control plane connection" description: "Connect API Platform Gateway to a WSO2 APIM or API Platform Cloud control plane for top-down or bottom-up API synchronization." canonical_url: https://wso2.com/api-platform/docs/api-gateway/deployment/production-deployment/control-plane-connection/ md_url: https://wso2.com/api-platform/docs/api-gateway/deployment/production-deployment/control-plane-connection.md @@ -12,7 +12,7 @@ last_updated: 2026-06-11 content_type: "how-to" --- -# Control Plane Connection +# Control plane connection !!! note This step is optional. Configure it only if the gateway needs to sync API artifacts from the [WSO2 APIM control plane](https://apim.docs.wso2.com/en/latest/api-gateway/platform-gateway/getting-started/) or [API Platform Cloud control plane](https://wso2.com/api-platform/docs/cloud/api-platform-gateway/getting-started/). @@ -33,7 +33,7 @@ The WSO2 API Platform gateway supports two fundamentally different deployment ap ```bash kubectl create secret generic gateway-cp-token \ --namespace \ - --from-literal=token='your-registration-token' + --from-literal=token='' ``` **Configure the chart:** @@ -74,7 +74,7 @@ The WSO2 API Platform gateway supports two fundamentally different deployment ap ```bash kubectl create secret generic gateway-cp-token \ --namespace \ - --from-literal=token='your-registration-token' + --from-literal=token='' ``` **Step 2: Generate OAuth2 client credentials** @@ -109,8 +109,8 @@ The WSO2 API Platform gateway supports two fundamentally different deployment ap namespace: ap-gateway # adjust to match your deployment namespace type: Opaque stringData: - APIP_GW_CONTROLLER_CONTROLPLANE_APIM__OAUTH2__CLIENT__ID: "your-client-id" - APIP_GW_CONTROLLER_CONTROLPLANE_APIM__OAUTH2__CLIENT__SECRET: "your-client-secret" + APIP_GW_CONTROLLER_CONTROLPLANE_APIM__OAUTH2__CLIENT__ID: "" + APIP_GW_CONTROLLER_CONTROLPLANE_APIM__OAUTH2__CLIENT__SECRET: "" ``` Apply it: diff --git a/en/docs/api-gateway/deployment/production-deployment/database-configuration.md b/en/docs/api-gateway/deployment/production-deployment/database-configuration.md index b59ab7be..49b453f7 100644 --- a/en/docs/api-gateway/deployment/production-deployment/database-configuration.md +++ b/en/docs/api-gateway/deployment/production-deployment/database-configuration.md @@ -1,5 +1,5 @@ --- -title: "Database Configuration" +title: "Database configuration" description: "Configure PostgreSQL as the shared database for Gateway Controller replicas in high-availability production deployments." canonical_url: https://wso2.com/api-platform/docs/api-gateway/deployment/production-deployment/database-configuration/ md_url: https://wso2.com/api-platform/docs/api-gateway/deployment/production-deployment/database-configuration.md @@ -13,11 +13,11 @@ last_updated: 2026-06-11 content_type: "how-to" --- -# Database Configuration +# Database configuration PostgreSQL is required for high-availability production deployments. It removes the single-replica constraint of the default SQLite backend and acts as the shared source of truth across all Gateway Controller replicas. See [Architecture](../high-availability-production-deployment.md#architecture) for how replicas coordinate via the shared database. -## Create the Database +## Create the database Connect to your PostgreSQL instance: @@ -33,19 +33,19 @@ Create the application database, user, and grant privileges: ```sql CREATE DATABASE gateway_controller; -CREATE USER gateway WITH PASSWORD 'your-db-password'; +CREATE USER gateway WITH PASSWORD ''; GRANT ALL PRIVILEGES ON DATABASE gateway_controller TO gateway; ``` -## Store the Password in a Kubernetes Secret +## Store the password in a Kubernetes secret ```bash kubectl create secret generic gateway-postgres-password \ --namespace \ - --from-literal=password='your-db-password' + --from-literal=password='' ``` -## Configure the Chart +## Configure the chart ```yaml gateway: @@ -78,7 +78,7 @@ gateway: enabled: false ``` -## DSN Alternative +## DSN alternative If your PostgreSQL connection string is managed externally (for example, from a secrets manager), you can supply a full DSN instead of individual fields. @@ -87,7 +87,7 @@ Create a secret containing the DSN: ```bash kubectl create secret generic gateway-postgres-dsn \ --namespace \ - --from-literal=dsn='postgres://gateway:your-db-password@postgres.example.internal:5432/gateway_controller?sslmode=require' + --from-literal=dsn='postgres://gateway:@postgres.example.internal:5432/gateway_controller?sslmode=require' ``` Reference the secret in values: @@ -110,7 +110,7 @@ gateway: !!! note When `dsn` is set, it takes precedence over all individual connection fields. The password environment variable is still injected from the referenced secret. -## Connection Pool Tuning +## Connection pool tuning | Parameter | Default | When to Adjust | |-----------|---------|----------------| diff --git a/en/docs/api-gateway/deployment/production-deployment/deploy-and-verify.md b/en/docs/api-gateway/deployment/production-deployment/deploy-and-verify.md index 6e6b5e98..bc863c7f 100644 --- a/en/docs/api-gateway/deployment/production-deployment/deploy-and-verify.md +++ b/en/docs/api-gateway/deployment/production-deployment/deploy-and-verify.md @@ -1,5 +1,5 @@ --- -title: "Deploy and Verify the Gateway" +title: "Deploy and verify the gateway" description: "Install API Platform Gateway using Helm, verify that pods and services are healthy, and perform upgrade and rollback procedures." canonical_url: https://wso2.com/api-platform/docs/api-gateway/deployment/production-deployment/deploy-and-verify/ md_url: https://wso2.com/api-platform/docs/api-gateway/deployment/production-deployment/deploy-and-verify.md @@ -13,9 +13,9 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# Deploy & Verify +# Deploy and verify -## Deploy the Chart +## Deploy the chart === "OCI Registry (Recommended)" @@ -40,7 +40,7 @@ content_type: "how-to" --timeout 5m ``` -## Verify the Deployment +## Verify the deployment **Check all pods are running:** @@ -61,7 +61,7 @@ kubectl exec -n ap-gateway deploy/ap-gateway-controller -- \ wget -qO- http://localhost:9094/api/admin/v0.9/health ``` -## Upgrade Procedure +## Upgrade procedure **Pull latest chart values to see what changed:** diff --git a/en/docs/api-gateway/deployment/production-deployment/resources-and-scaling.md b/en/docs/api-gateway/deployment/production-deployment/resources-and-scaling.md index 48f5d86d..c20369bb 100644 --- a/en/docs/api-gateway/deployment/production-deployment/resources-and-scaling.md +++ b/en/docs/api-gateway/deployment/production-deployment/resources-and-scaling.md @@ -1,5 +1,5 @@ --- -title: "Configure Resources and Scaling" +title: "Configure resources and scaling" description: "Set CPU and memory resource limits, pod anti-affinity rules, Horizontal Pod Autoscaler, and Pod Disruption Budget for API Platform Gateway." canonical_url: https://wso2.com/api-platform/docs/api-gateway/deployment/production-deployment/resources-and-scaling/ md_url: https://wso2.com/api-platform/docs/api-gateway/deployment/production-deployment/resources-and-scaling.md @@ -14,9 +14,9 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# Resources & Scaling +# Resources and scaling -## Resource Limits +## Resource limits !!! note Always set resource limits in production to prevent runaway resource consumption from affecting other workloads on the node. @@ -53,7 +53,7 @@ gateway: memory: 2Gi ``` -## Pod Anti-Affinity +## Pod anti-affinity Pod anti-affinity rules control how replicas are spread across your cluster. Two topology keys are most relevant for production: @@ -101,9 +101,9 @@ affinity: Apply the same anti-affinity configuration to `gateway.gatewayRuntime` to spread runtime replicas across nodes and zones as well. -## Horizontal Pod Autoscaler & Pod Disruption Budget +## Horizontal pod autoscaler and pod disruption budget -### Horizontal Pod Autoscaler +### Horizontal pod autoscaler HPA automatically adjusts the number of replicas based on CPU and memory utilization. Apply the following configuration to both `gateway.controller` and `gateway.gatewayRuntime`: @@ -121,7 +121,7 @@ hpa: !!! note Setting `minReplicas: 2` ensures at least two replicas are always running, which is required for high availability. Do not set this to `1` in production. -### Pod Disruption Budget +### Pod disruption budget A PDB guarantees that a minimum number of replicas remain available during voluntary disruptions: diff --git a/en/docs/api-gateway/deployment/production-deployment/security-hardening.md b/en/docs/api-gateway/deployment/production-deployment/security-hardening.md index 4522c822..05ef4a45 100644 --- a/en/docs/api-gateway/deployment/production-deployment/security-hardening.md +++ b/en/docs/api-gateway/deployment/production-deployment/security-hardening.md @@ -1,5 +1,5 @@ --- -title: "Security Hardening" +title: "Security hardening" description: "Configure the necessary security areas before deploying API Platform Gateway to production." canonical_url: https://wso2.com/api-platform/docs/api-gateway/deployment/production-deployment/security-hardening/ md_url: https://wso2.com/api-platform/docs/api-gateway/deployment/production-deployment/security-hardening.md @@ -12,11 +12,11 @@ last_updated: 2026-06-11 content_type: "how-to" --- -# Security Hardening +# Security hardening This page covers the three security areas that must be configured before a production deployment: encryption keys for data at rest, TLS for data in transit, and authentication for access control. -## Encryption Keys +## Encryption keys The controller uses AES-GCM 256-bit keys to encrypt sensitive data at rest. Providing at least one encryption key is required when `developmentMode` is set to `false`. @@ -80,7 +80,7 @@ The `version` field must match the filename stem of the secret key (`default-aes --- -## TLS Configuration +## TLS configuration TLS must be configured before exposing the gateway externally. Choose one of the options below based on how certificates are managed in your environment. @@ -127,7 +127,7 @@ TLS must be configured before exposing the gateway externally. Choose one of the renewBefore: 720h # Renew 30 days before expiry ``` -=== "Option B: Existing TLS Secret" +=== "Option B: Existing TLS secret" Use this option if certificates are managed externally, for example, via a corporate PKI or HashiCorp Vault. @@ -154,7 +154,7 @@ TLS must be configured before exposing the gateway externally. Choose one of the keyKey: tls.key ``` -### Upstream Custom CA Certificates +### Upstream custom CA certificates If backend services use certificates signed by a private CA, mount the CA bundle into the controller so it can verify upstream TLS connections. @@ -206,7 +206,7 @@ Choose an authentication strategy based on your organizational requirements. !!! note Role mapping values must correspond to claims present in the JWT issued by your IDP. See the [Gateway Controller OpenAPI reference](https://raw.githubusercontent.com/wso2/api-platform/refs/tags/gateway/v1.1.0/gateway/gateway-controller/api/management-openapi.yaml) for the full list of supported roles and their permissions. -=== "Option B: Basic Auth with Bcrypt" +=== "Option B: Basic auth with bcrypt" If basic auth is required, never store plain-text passwords. The controller supports bcrypt hashes, which are safe to include in Helm values (the hash is not reversible). Store the plain password separately in a Kubernetes secret for rotation reference only. @@ -215,14 +215,14 @@ Choose an authentication strategy based on your organizational requirements. Requires `apache2-utils` (Debian/Ubuntu) or `httpd-tools` (RHEL/CentOS): ```bash - htpasswd -nbB admin 'your-secure-password' | cut -d: -f2 + htpasswd -nbB admin '' | cut -d: -f2 # Output: $2y$10$... ``` On macOS without `htpasswd`: ```bash - docker run --rm httpd:alpine htpasswd -nbB admin 'your-secure-password' | cut -d: -f2 + docker run --rm httpd:alpine htpasswd -nbB admin '' | cut -d: -f2 ``` **Store the plain password in a Kubernetes secret:** @@ -233,7 +233,7 @@ Choose an authentication strategy based on your organizational requirements. kubectl create secret generic gateway-admin-credentials \ --namespace \ --from-literal=username=admin \ - --from-literal=password='your-secure-password' + --from-literal=password='' ``` **Configure the chart with the bcrypt hash:** diff --git a/en/docs/api-gateway/gateway-controller-management-api/authentication.md b/en/docs/api-gateway/gateway-controller-management-api/authentication.md index db566c27..921c8348 100644 --- a/en/docs/api-gateway/gateway-controller-management-api/authentication.md +++ b/en/docs/api-gateway/gateway-controller-management-api/authentication.md @@ -1,5 +1,5 @@ --- -title: "Authenticate to the Management API" +title: "Authenticate to the management API" description: "Configure Basic Auth or JWT/IDP authentication and role-based authorization for the API Platform Gateway Controller management REST API." canonical_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/authentication/ md_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/authentication.md @@ -13,31 +13,31 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# Authentication & Authorization in Gateway Controller +# Authentication and authorization in gateway controller ## Overview The Gateway Controller REST API (the control-plane API used to manage gateway configuration) can be protected using either locally configured users (Basic Auth) or an external Identity Provider (JWT validation via JWKS). Authorization is role-based and enforced per API route. -## How It Works +## How it works -### Authentication (Who are you?) +### Authentication (who are you?) You can enable one (or both) of the following: - **Basic Auth (local users)**: Define usernames/passwords and assign local roles. - **IDP/JWT (external users)**: Validate incoming JWTs using `jwks_url` optionally `issuer`. -**No Authentication (open access)**: If BOTH `basic.enabled` and `idp.enabled` are set to `false`, all requests to the gateway controller are allowed without authentication. +**No authentication (open access)**: If both `basic.enabled` and `idp.enabled` are set to `false`, all requests to the gateway controller are allowed without authentication. -### Authorization (Are you allowed?) +### Authorization (are you allowed?) Gateway Controller routes are protected using **local roles** (for example `admin`, `developer`, `consumer`). -- If **`roles_claim` is NOT configured** in the IDP/JWT setup, **authorization is bypassed** for the Gateway Controller REST API routes (i.e., no role checks are performed). -- If **`roles_claim` IS configured**, you **must** also configure **`role_mapping`**. Without a mapping, the controller cannot translate IDP roles → local roles, and requests will be denied. +- If **`roles_claim` is not configured** in the IDP/JWT setup, **authorization is bypassed** for the Gateway Controller REST API routes (i.e., no role checks are performed). +- If **`roles_claim` is configured**, you **must** also configure **`role_mapping`**. Without a mapping, the controller cannot translate IDP roles → local roles, and requests will be denied. ## Configuration In the umbrella gateway config, these settings live under `controller.auth`. (If you run the controller standalone, the same structure applies under the controller's config root.) -### Option A: Basic Auth (local users) +### Option A: Basic auth (local users) ```yaml controller: auth: @@ -72,7 +72,7 @@ controller: consumer: ["*"] ``` -## Role Mapping Semantics +## Role mapping semantics `role_mapping` is defined as: ```text @@ -93,7 +93,7 @@ role_mapping: ``` In this example, a user in `platform-admins` becomes both `admin` and `developer` in the Gateway Controller. -## Troubleshooting (What you’ll observe) +## Troubleshooting (what you’ll observe) - **Requests are denied after enabling JWT auth**: verify `jwks_url` and (if set) `issuer` match the token you're sending. - **You enabled `roles_claim` and suddenly everything is forbidden**: add `role_mapping` (mapping is mandatory when `roles_claim` is provided). - **Users authenticate but don't have expected access**: confirm the token actually contains the configured `roles_claim`, and that its values match what you listed in `role_mapping`. diff --git a/en/docs/api-gateway/gateway-controller-management-api/certificate-management.md b/en/docs/api-gateway/gateway-controller-management-api/certificate-management.md index a7255803..6d67c02c 100644 --- a/en/docs/api-gateway/gateway-controller-management-api/certificate-management.md +++ b/en/docs/api-gateway/gateway-controller-management-api/certificate-management.md @@ -1,5 +1,5 @@ --- -title: "Management API: Certificate Management" +title: "Management API: certificate management" description: "REST API reference for managing custom TLS certificates in API Platform Gateway: list, upload, delete, and reload certificates dynamically." canonical_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/certificate-management/ md_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/certificate-management.md @@ -13,7 +13,7 @@ last_updated: 2026-06-17 content_type: "reference" --- -# Certificate Management +# Certificate management Manage custom TLS certificates for HTTPS upstream verification diff --git a/en/docs/api-gateway/gateway-controller-management-api/llm-provider-management.md b/en/docs/api-gateway/gateway-controller-management-api/llm-provider-management.md index 300999a5..75ab80b9 100644 --- a/en/docs/api-gateway/gateway-controller-management-api/llm-provider-management.md +++ b/en/docs/api-gateway/gateway-controller-management-api/llm-provider-management.md @@ -1,5 +1,5 @@ --- -title: "Management API: LLM Provider Management" +title: "Management API: LLM provider management" description: "REST API reference for creating, listing, updating, and deleting LLM provider configurations and API keys in API Platform Gateway." canonical_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/llm-provider-management/ md_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/llm-provider-management.md @@ -12,7 +12,7 @@ last_updated: 2026-06-17 content_type: "reference" --- -# LLM Provider Management +# LLM provider management CRUD operations for LLM Provider configurations @@ -204,7 +204,7 @@ Required roles: `admin`, `developer` |status|query|string|false|Filter by deployment status| |vhost|query|string|false|Filter by LLM provider vhost| -#### Enumerated Values +#### Enumerated values |Parameter|Value| |---|---| @@ -374,7 +374,7 @@ Status Code **200** |»»»» updatedAt|string(date-time)|false|none|Timestamp when the resource was last updated (UTC)| |»»»» deployedAt|string(date-time)|false|none|Timestamp when the resource was last deployed (omitted when undeployed)| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| diff --git a/en/docs/api-gateway/gateway-controller-management-api/llm-provider-template-management.md b/en/docs/api-gateway/gateway-controller-management-api/llm-provider-template-management.md index 8be3d36d..a07af0bc 100644 --- a/en/docs/api-gateway/gateway-controller-management-api/llm-provider-template-management.md +++ b/en/docs/api-gateway/gateway-controller-management-api/llm-provider-template-management.md @@ -1,5 +1,5 @@ --- -title: "Management API: LLM Provider Template Management" +title: "Management API: LLM provider template management" description: "REST API reference for creating, listing, updating, and deleting LLM provider templates in API Platform Gateway." canonical_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/llm-provider-template-management/ md_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/llm-provider-template-management.md @@ -12,7 +12,7 @@ last_updated: 2026-06-17 content_type: "reference" --- -# LLM Provider Template Management +# LLM provider template management CRUD operations for LLM Provider Template configurations @@ -292,7 +292,7 @@ Status Code **200** |»»»» updatedAt|string(date-time)|false|none|Timestamp when the resource was last updated (UTC)| |»»»» deployedAt|string(date-time)|false|none|Timestamp when the resource was last deployed (omitted when undeployed)| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| diff --git a/en/docs/api-gateway/gateway-controller-management-api/llm-proxy-management.md b/en/docs/api-gateway/gateway-controller-management-api/llm-proxy-management.md index c00a25f3..f8553f66 100644 --- a/en/docs/api-gateway/gateway-controller-management-api/llm-proxy-management.md +++ b/en/docs/api-gateway/gateway-controller-management-api/llm-proxy-management.md @@ -1,5 +1,5 @@ --- -title: "Management API: LLM Proxy Management" +title: "Management API: LLM proxy management" description: "REST API reference for creating, listing, updating, and deleting LLM proxy configurations and API keys in API Platform Gateway." canonical_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/llm-proxy-management/ md_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/llm-proxy-management.md @@ -12,7 +12,7 @@ last_updated: 2026-06-17 content_type: "reference" --- -# LLM Proxy Management +# LLM proxy management CRUD operations for LLM Proxy configurations @@ -148,7 +148,7 @@ Required roles: `admin`, `developer` |status|query|string|false|Filter by deployment status| |vhost|query|string|false|Filter by LLM proxy vhost| -#### Enumerated Values +#### Enumerated values |Parameter|Value| |---|---| @@ -253,7 +253,7 @@ Status Code **200** |»»»» updatedAt|string(date-time)|false|none|Timestamp when the resource was last updated (UTC)| |»»»» deployedAt|string(date-time)|false|none|Timestamp when the resource was last deployed (omitted when undeployed)| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| diff --git a/en/docs/api-gateway/gateway-controller-management-api/mcp-proxy-management.md b/en/docs/api-gateway/gateway-controller-management-api/mcp-proxy-management.md index efad39a2..beccf74b 100644 --- a/en/docs/api-gateway/gateway-controller-management-api/mcp-proxy-management.md +++ b/en/docs/api-gateway/gateway-controller-management-api/mcp-proxy-management.md @@ -1,5 +1,5 @@ --- -title: "Management API: MCP Proxy Management" +title: "Management API: MCP proxy management" description: "REST API reference for creating, listing, updating, and deleting MCP proxy configurations in API Platform Gateway." canonical_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/mcp-proxy-management/ md_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/mcp-proxy-management.md @@ -12,11 +12,11 @@ last_updated: 2026-06-17 content_type: "reference" --- -# MCP Proxy Management +# MCP proxy management CRUD operations for MCPProxies -## Create a new MCPProxy +## Create a new mcpproxy @@ -117,7 +117,7 @@ Required roles: `admin`, `developer` |409|[Conflict](https://tools.ietf.org/html/rfc7231#section-6.5.8)|Conflict - MCP Proxy with same name and version already exists|[ErrorResponse](schemas.md#schemaerrorresponse)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error|[ErrorResponse](schemas.md#schemaerrorresponse)| -## List all MCPProxies +## List all mcpproxies @@ -153,7 +153,7 @@ Required roles: `admin`, `developer` |context|query|string|false|Filter by MCP proxy context/path| |status|query|string|false|Filter by deployment status| -#### Enumerated Values +#### Enumerated values |Parameter|Value| |---|---| @@ -313,7 +313,7 @@ Status Code **200** |»»»» updatedAt|string(date-time)|false|none|Timestamp when the resource was last updated (UTC)| |»»»» deployedAt|string(date-time)|false|none|Timestamp when the resource was last deployed (omitted when undeployed)| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -327,7 +327,7 @@ Status Code **200** |state|deployed| |state|undeployed| -## Get MCPProxy by id +## Get mcpproxy by id @@ -405,7 +405,7 @@ Required roles: `admin`, `developer` |404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|MCPProxy not found|[ErrorResponse](schemas.md#schemaerrorresponse)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error|[ErrorResponse](schemas.md#schemaerrorresponse)| -## Update an existing MCPProxy +## Update an existing mcpproxy @@ -511,7 +511,7 @@ Required roles: `admin`, `developer` |404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|MCPProxy not found|[ErrorResponse](schemas.md#schemaerrorresponse)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error|[ErrorResponse](schemas.md#schemaerrorresponse)| -## Delete a MCPProxy +## Delete a mcpproxy diff --git a/en/docs/api-gateway/gateway-controller-management-api/overview.md b/en/docs/api-gateway/gateway-controller-management-api/overview.md index ef5e890c..026086af 100644 --- a/en/docs/api-gateway/gateway-controller-management-api/overview.md +++ b/en/docs/api-gateway/gateway-controller-management-api/overview.md @@ -1,5 +1,5 @@ --- -title: "Gateway Controller Management API" +title: "Gateway controller management API" description: "Overview of the API Platform Gateway Controller REST API for managing REST APIs, MCP proxies, LLM providers, certificates, and secrets." canonical_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/overview/ md_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/overview.md @@ -11,7 +11,7 @@ last_updated: 2026-06-17 content_type: "overview" --- -# Gateway Controller Management API v0.9.0 +# Gateway controller management API v0.9.0 The Gateway Controller Management API is a RESTful API for managing configurations in the WSO2 API Platform Gateway. @@ -20,7 +20,7 @@ The API exposes the following endpoints: * `http://localhost:9090/api/management/v0.9` * `http://gateway-controller:9090/api/management/v0.9` -## Table of Contents +## Table of contents ### [Authentication](authentication.md) @@ -54,7 +54,7 @@ The API exposes the following endpoints: - [Update a subscription](rest-api-management.md#update-a-subscription) - [Delete a subscription](rest-api-management.md#delete-a-subscription) -### [MCP Proxy Management](mcp-proxy-management.md) +### [MCP proxy Management](mcp-proxy-management.md) - [Create a new MCPProxy](mcp-proxy-management.md#create-a-new-mcpproxy) - [List all MCPProxies](mcp-proxy-management.md#list-all-mcpproxies) @@ -69,7 +69,7 @@ The API exposes the following endpoints: - [Delete a certificate](certificate-management.md#delete-a-certificate) - [Manually reload certificates](certificate-management.md#manually-reload-certificates) -### [LLM Provider Template Management](llm-provider-template-management.md) +### [LLM provider template Management](llm-provider-template-management.md) - [Create a new LLM provider template](llm-provider-template-management.md#create-a-new-llm-provider-template) - [List all LLM provider templates](llm-provider-template-management.md#list-all-llm-provider-templates) @@ -77,7 +77,7 @@ The API exposes the following endpoints: - [Update an existing LLM provider template](llm-provider-template-management.md#update-an-existing-llm-provider-template) - [Delete an LLM provider template](llm-provider-template-management.md#delete-an-llm-provider-template) -### [LLM Provider Management](llm-provider-management.md) +### [LLM provider Management](llm-provider-management.md) - [Create a new LLM provider](llm-provider-management.md#create-a-new-llm-provider) - [List all LLM providers](llm-provider-management.md#list-all-llm-providers) @@ -90,7 +90,7 @@ The API exposes the following endpoints: - [Update an API key for an LLM provider](llm-provider-management.md#update-an-api-key-for-an-llm-provider) - [Revoke an API key for an LLM provider](llm-provider-management.md#revoke-an-api-key-for-an-llm-provider) -### [LLM Proxy Management](llm-proxy-management.md) +### [LLM proxy Management](llm-proxy-management.md) - [Create a new LLM proxy](llm-proxy-management.md#create-a-new-llm-proxy) - [List all LLM proxies](llm-proxy-management.md#list-all-llm-proxies) diff --git a/en/docs/api-gateway/gateway-controller-management-api/rest-api-management.md b/en/docs/api-gateway/gateway-controller-management-api/rest-api-management.md index adf40532..5226f278 100644 --- a/en/docs/api-gateway/gateway-controller-management-api/rest-api-management.md +++ b/en/docs/api-gateway/gateway-controller-management-api/rest-api-management.md @@ -1,5 +1,5 @@ --- -title: "Management API: REST API Management" +title: "Management API: REST API management" description: "REST API reference for creating, listing, updating, and deleting REST API configurations, API keys, and subscriptions via the Gateway Controller." canonical_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/rest-api-management/ md_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/rest-api-management.md @@ -12,11 +12,11 @@ last_updated: 2026-06-17 content_type: "reference" --- -# Rest API Management +# Rest API management CRUD operations for Rest APIs -## Create a new RestAPI +## Create a new restapi @@ -205,7 +205,7 @@ Required roles: `admin`, `developer` |409|[Conflict](https://tools.ietf.org/html/rfc7231#section-6.5.8)|Conflict - API with same name and version already exists|[ErrorResponse](schemas.md#schemaerrorresponse)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error|[ErrorResponse](schemas.md#schemaerrorresponse)| -## List all RestAPIs +## List all restapis @@ -241,7 +241,7 @@ Required roles: `admin`, `developer` |context|query|string|false|Filter by API context/path| |status|query|string|false|Filter by deployment status| -#### Enumerated Values +#### Enumerated values |Parameter|Value| |---|---| @@ -423,7 +423,7 @@ Status Code **200** |»»»» updatedAt|string(date-time)|false|none|Timestamp when the resource was last updated (UTC)| |»»»» deployedAt|string(date-time)|false|none|Timestamp when the resource was last deployed (omitted when undeployed)| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -443,7 +443,7 @@ Status Code **200** |state|deployed| |state|undeployed| -## Get RestAPI by id +## Get restapi by id @@ -565,7 +565,7 @@ Required roles: `admin`, `developer` |404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|RestAPI not found|[ErrorResponse](schemas.md#schemaerrorresponse)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error|[ErrorResponse](schemas.md#schemaerrorresponse)| -## Update an existing RestAPI +## Update an existing restapi @@ -759,7 +759,7 @@ Required roles: `admin`, `developer` |404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|RestAPI not found|[ErrorResponse](schemas.md#schemaerrorresponse)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error|[ErrorResponse](schemas.md#schemaerrorresponse)| -## Delete a RestAPI +## Delete a restapi @@ -1646,7 +1646,7 @@ Required roles: `admin`, `developer` |applicationId|query|string|false|none| |status|query|string|false|none| -#### Enumerated Values +#### Enumerated values |Parameter|Value| |---|---| diff --git a/en/docs/api-gateway/gateway-controller-management-api/schemas.md b/en/docs/api-gateway/gateway-controller-management-api/schemas.md index 168d4330..20702b70 100644 --- a/en/docs/api-gateway/gateway-controller-management-api/schemas.md +++ b/en/docs/api-gateway/gateway-controller-management-api/schemas.md @@ -1,5 +1,5 @@ --- -title: "Management API Schemas" +title: "Management API schemas" description: "JSON schema definitions for all API Platform Gateway Controller management API request and response objects." canonical_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/schemas/ md_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/schemas.md @@ -43,7 +43,7 @@ Server-managed lifecycle information for a resource |updatedAt|string(date-time)|false|none|Timestamp when the resource was last updated (UTC)| |deployedAt|string(date-time)|false|none|Timestamp when the resource was last deployed (omitted when undeployed)| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -133,7 +133,7 @@ Server-managed lifecycle information for a resource |metadata|[Metadata](#schemametadata)|true|none|none| |spec|[APIConfigData](#schemaapiconfigdata)|true|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -278,7 +278,7 @@ and |metadata|[Metadata](#schemametadata)|true|none|none| |spec|[WebhookAPIData](#schemawebhookapidata)|true|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -465,7 +465,7 @@ and |operations|[[Operation](#schemaoperation)]|true|none|List of HTTP operations/routes| |deploymentState|string|false|none|Desired deployment state - 'deployed' (default) or 'undeployed'. When set to 'undeployed', the API is removed from router traffic but configuration, API keys, and policies are preserved for potential redeployment.| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -569,7 +569,7 @@ xor |---|---|---|---|---| |*anonymous*|object|false|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -607,7 +607,7 @@ xor |path|string|true|none|Route path with optional {param} placeholders| |policies|[[Policy](#schemapolicy)]|false|none|List of policies applied only to this operation (overrides or adds to API-level policies)| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -809,7 +809,7 @@ xor |» **additionalProperties**|[WebSubChannel](#schemawebsubchannel)|false|none|A single channel definition with optional per-channel policy overrides.| |deploymentState|string|false|none|Desired deployment state - 'deployed' (default) or 'undeployed'. When set to 'undeployed', the API is removed from router traffic but configuration, API keys, and policies are preserved for potential redeployment.| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -1062,7 +1062,7 @@ Channel (topic/event stream) definition for async APIs. |method|string|true|none|Operation method type.| |policies|[[Policy](#schemapolicy)]|false|none|List of policies applied only to this channel (overrides or adds to API-level policies)| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -1144,7 +1144,7 @@ Channel (topic/event stream) definition for async APIs. |metadata|[Metadata](#schemametadata)|true|none|none| |spec|[WebBrokerApiData](#schemawebbrokerapidata)|true|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -1403,7 +1403,7 @@ and |» sandbox|string|false|none|Custom virtual host/domain for sandbox traffic| |deploymentState|string|false|none|Desired deployment state - 'deployed' (default) or 'undeployed'. When set to 'undeployed', the API is removed from router traffic but configuration and policies are preserved for potential redeployment.| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -1682,7 +1682,7 @@ Configuration for consuming messages from Kafka to WebSocket |externalRefId|string|false|none|External reference ID for the API key.
This field is optional and used for tracing purposes only.
The gateway generates its own internal ID for tracking.| |issuer|string|false|none|Identifies the portal that created this key. If provided, only api keys generated from
the same portal will be accepted. If not provided, there is no portal restriction.| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -1768,7 +1768,7 @@ Details of an API key |source|string|true|none|Source of the API key (local or external)| |externalRefId|string|false|none|External reference ID for the API key| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -1799,7 +1799,7 @@ Details of an API key |» duration|integer|true|none|Duration value for expiration| |expiresAt|string(date-time)|false|none|Expiration timestamp| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -1882,7 +1882,7 @@ Details of an API key |expiryTime|string(date-time)|false|none|none| |status|string|false|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -1925,7 +1925,7 @@ Details of an API key |expiryTime|string(date-time)|false|none|none| |status|string|false|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -1976,7 +1976,7 @@ Details of an API key |createdAt|string(date-time)|false|none|none| |updatedAt|string(date-time)|false|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -2051,7 +2051,7 @@ Details of an API key |billingSubscriptionId|string|false|none|Billing subscription identifier (optional, for analytics tracking).| |status|string|false|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -2079,7 +2079,7 @@ Details of an API key |---|---|---|---|---| |status|string|false|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -2127,7 +2127,7 @@ Details of an API key |createdAt|string(date-time)|false|none|none| |updatedAt|string(date-time)|false|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -2210,7 +2210,7 @@ Details of an API key |metadata|[Metadata](#schemametadata)|true|none|none| |spec|[MCPProxyConfigData](#schemamcpproxyconfigdata)|true|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -2373,7 +2373,7 @@ continued |prompts|[[MCPPrompt](#schemamcpprompt)]|false|none|none| |deploymentState|string|false|none|Desired deployment state - 'deployed' (default) or 'undeployed'. When set to 'undeployed', the MCP Proxy is removed from router traffic but configuration and policies are preserved for potential redeployment.| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -2580,7 +2580,7 @@ continued |metadata|[Metadata](#schemametadata)|true|none|none| |spec|[LLMProviderTemplateData](#schemallmprovidertemplatedata)|true|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -2854,7 +2854,7 @@ and |location|string|true|none|Where to find the token information| |identifier|string|true|none|JSONPath expression or header name to identify the token value| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -2927,7 +2927,7 @@ and |metadata|[Metadata](#schemametadata)|true|none|none| |spec|[LLMProviderConfigData](#schemallmproviderconfigdata)|true|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -3097,7 +3097,7 @@ continued |policies|[[LLMPolicy](#schemallmpolicy)]|false|none|List of policies applied only to this operation (overrides or adds to API-level policies)| |deploymentState|string|false|none|Desired deployment state - 'deployed' (default) or 'undeployed'. When set to 'undeployed', the LLM Provider is removed from router traffic but configuration and policies are preserved for potential redeployment.| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -3131,7 +3131,7 @@ continued |» header|string|false|none|none| |» value|string|false|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -3161,7 +3161,7 @@ continued |header|string|false|none|none| |value|string|false|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -3222,7 +3222,7 @@ continued |mode|string|true|none|Access control mode| |exceptions|[[RouteException](#schemarouteexception)]|false|none|Path exceptions to the access control mode| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -3347,7 +3347,7 @@ continued |metadata|[Metadata](#schemametadata)|true|none|none| |spec|[LLMProxyConfigData](#schemallmproxyconfigdata)|true|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -3456,7 +3456,7 @@ and |policies|[[LLMPolicy](#schemallmpolicy)]|false|none|List of policies applied only to this operation (overrides or adds to API-level policies)| |deploymentState|string|false|none|Desired deployment state - 'deployed' (default) or 'undeployed'. When set to 'undeployed', the LLM Proxy is removed from router traffic but configuration and policies are preserved for potential redeployment.| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -3495,7 +3495,7 @@ and |metadata|[Metadata](#schemametadata)|true|none|none| |spec|[SecretConfigData](#schemasecretconfigdata)|true|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -3632,7 +3632,7 @@ and |spec|[SecretConfigListData](#schemasecretconfiglistdata)|true|none|none| |status|[ResourceStatus](#schemaresourcestatus)|false|read-only|Server-managed lifecycle fields. Omitted in list items may vary; the secret value is never included here.| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -3695,7 +3695,7 @@ and |message|string|false|none|Success or informational message| |status|string|false|none|none| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -3881,7 +3881,7 @@ POST/PUT /secrets response. `spec.value` is not returned; see SecretConfiguratio |spec|[SecretConfigListData](#schemasecretconfiglistdata)|true|none|none| |status|[SecretResourceServiceStatus](#schemasecretresourceservicestatus)|true|none|Id and optional timestamps. Not the full ResourceStatus model (no `state` or
`deployedAt`).| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -3928,7 +3928,7 @@ GET /secrets/{id} response including decrypted `spec.value`. |spec|[SecretConfigData](#schemasecretconfigdata)|true|none|none| |status|[SecretResourceServiceStatus](#schemasecretresourceservicestatus)|true|none|Id and optional timestamps. Not the full ResourceStatus model (no `state` or
`deployedAt`).| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| diff --git a/en/docs/api-gateway/gateway-controller-management-api/secrets-management.md b/en/docs/api-gateway/gateway-controller-management-api/secrets-management.md index dd5d686b..bb1cab3c 100644 --- a/en/docs/api-gateway/gateway-controller-management-api/secrets-management.md +++ b/en/docs/api-gateway/gateway-controller-management-api/secrets-management.md @@ -1,5 +1,5 @@ --- -title: "Management API: Secrets Management" +title: "Management API: secrets management" description: "REST API reference for creating, listing, retrieving, updating, and deleting secrets in API Platform Gateway." canonical_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/secrets-management/ md_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/secrets-management.md @@ -12,7 +12,7 @@ last_updated: 2026-06-17 content_type: "reference" --- -# Secrets Management +# Secrets management CRUD operations for Secrets diff --git a/en/docs/api-gateway/gateway-controller-management-api/webbroker-api-management.md b/en/docs/api-gateway/gateway-controller-management-api/webbroker-api-management.md index a731e8e8..4ff6344f 100644 --- a/en/docs/api-gateway/gateway-controller-management-api/webbroker-api-management.md +++ b/en/docs/api-gateway/gateway-controller-management-api/webbroker-api-management.md @@ -1,5 +1,5 @@ --- -title: "Management API: WebBroker API Management" +title: "Management API: WebBroker API management" description: "REST API reference for creating, listing, retrieving, and deleting WebBroker API configurations in API Platform Gateway." canonical_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/webbroker-api-management/ md_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/webbroker-api-management.md @@ -11,9 +11,9 @@ last_updated: 2026-06-17 content_type: "reference" --- -# WebBroker API Management +# WebBroker API management -## Create a new WebBrokerAPI +## Create a new webbrokerapi @@ -188,7 +188,7 @@ Required roles: `admin`, `developer` |409|[Conflict](https://tools.ietf.org/html/rfc7231#section-6.5.8)|Conflict - WebBroker API with same name and version already exists|[ErrorResponse](schemas.md#schemaerrorresponse)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error|[ErrorResponse](schemas.md#schemaerrorresponse)| -## List all WebBrokerAPIs +## List all webbrokerapis @@ -223,7 +223,7 @@ Required roles: `admin`, `developer` |version|query|string|false|Filter by WebBroker API version| |status|query|string|false|Filter by deployment status| -#### Enumerated Values +#### Enumerated values |Parameter|Value| |---|---| @@ -383,7 +383,7 @@ Status Code **200** |»»»» updatedAt|string(date-time)|false|none|Timestamp when the resource was last updated (UTC)| |»»»» deployedAt|string(date-time)|false|none|Timestamp when the resource was last deployed (omitted when undeployed)| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -394,7 +394,7 @@ Status Code **200** |state|deployed| |state|undeployed| -## Get WebBrokerAPI by id +## Get webbrokerapi by id @@ -509,7 +509,7 @@ Required roles: `admin`, `developer` |404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|WebBrokerAPI not found|[ErrorResponse](schemas.md#schemaerrorresponse)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error|[ErrorResponse](schemas.md#schemaerrorresponse)| -## Delete a WebBrokerAPI +## Delete a webbrokerapi diff --git a/en/docs/api-gateway/gateway-controller-management-api/websub-api-management.md b/en/docs/api-gateway/gateway-controller-management-api/websub-api-management.md index e2a08427..4a39990f 100644 --- a/en/docs/api-gateway/gateway-controller-management-api/websub-api-management.md +++ b/en/docs/api-gateway/gateway-controller-management-api/websub-api-management.md @@ -1,5 +1,5 @@ --- -title: "Management API: WebSub API Management" +title: "Management API: WebSub API management" description: "REST API reference for creating, listing, updating, and deleting WebSub API configurations and API keys in API Platform Gateway." canonical_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/websub-api-management/ md_url: https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/websub-api-management.md @@ -11,9 +11,9 @@ last_updated: 2026-06-17 content_type: "reference" --- -# WebSub API Management +# WebSub API management -## Create a new WebSubAPI +## Create a new websubapi @@ -120,7 +120,7 @@ Required roles: `admin`, `developer` |409|[Conflict](https://tools.ietf.org/html/rfc7231#section-6.5.8)|Conflict - WebSub API with same name and version already exists|[ErrorResponse](schemas.md#schemaerrorresponse)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error|[ErrorResponse](schemas.md#schemaerrorresponse)| -## List all WebSubAPIs +## List all websubapis @@ -156,7 +156,7 @@ Required roles: `admin`, `developer` |context|query|string|false|Filter by WebSub API context/path| |status|query|string|false|Filter by deployment status| -#### Enumerated Values +#### Enumerated values |Parameter|Value| |---|---| @@ -272,7 +272,7 @@ Status Code **200** |»»»» updatedAt|string(date-time)|false|none|Timestamp when the resource was last updated (UTC)| |»»»» deployedAt|string(date-time)|false|none|Timestamp when the resource was last deployed (omitted when undeployed)| -#### Enumerated Values +#### Enumerated values |Property|Value| |---|---| @@ -632,7 +632,7 @@ Required roles: `admin`, `consumer` |404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|WebSub API or API key not found|[ErrorResponse](schemas.md#schemaerrorresponse)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error|[ErrorResponse](schemas.md#schemaerrorresponse)| -## Get WebSubAPI by id +## Get websubapi by id @@ -713,7 +713,7 @@ Required roles: `admin`, `developer` |404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|WebSubAPI not found|[ErrorResponse](schemas.md#schemaerrorresponse)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error|[ErrorResponse](schemas.md#schemaerrorresponse)| -## Update an existing WebSubAPI +## Update an existing websubapi @@ -825,7 +825,7 @@ Required roles: `admin`, `developer` |404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|WebSubAPI not found|[ErrorResponse](schemas.md#schemaerrorresponse)| |500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error|[ErrorResponse](schemas.md#schemaerrorresponse)| -## Delete a WebSubAPI +## Delete a websubapi diff --git a/en/docs/api-gateway/observability/logging.md b/en/docs/api-gateway/observability/logging.md index b0a6260d..a46a8017 100644 --- a/en/docs/api-gateway/observability/logging.md +++ b/en/docs/api-gateway/observability/logging.md @@ -1,5 +1,5 @@ --- -title: "Configure Centralized Logging" +title: "Configure centralized logging" description: "Set up centralized log collection for API Platform Gateway using Fluent Bit, OpenSearch, and OpenSearch Dashboards." canonical_url: https://wso2.com/api-platform/docs/api-gateway/observability/logging/ md_url: https://wso2.com/api-platform/docs/api-gateway/observability/logging.md @@ -12,7 +12,7 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# Gateway Logging +# Gateway logging This guide explains how to implement and configure logging for the API Platform Gateway components. @@ -22,7 +22,7 @@ The default logging services included in the Docker Compose configuration are ** **Important**: You are free to choose any logging or observability strategy that suits your environment and requirements. The provided setup is just one of many possible configurations. -## Logging Architecture +## Logging architecture The default logging stack consists of: @@ -30,7 +30,7 @@ The default logging stack consists of: - **OpenSearch**: Stores and indexes log data for searchability and analysis - **OpenSearch Dashboards**: Web interface for visualizing, exploring, and searching logs -### How It Works +### How it works 1. Gateway components (gateway-controller, policy-engine, router) write structured JSON logs to stdout/stderr 2. Docker captures these logs and stores them in `/var/lib/docker/containers` @@ -38,9 +38,9 @@ The default logging stack consists of: 4. Fluent Bit forwards processed logs to OpenSearch 5. Users can view and search logs through OpenSearch Dashboards -## Enabling Logging Services +## Enabling logging services -### Gateway Components Already Log to Standard Output +### Gateway components already log to standard output **No special configuration is required to enable logging in the gateway components.** All gateway components (gateway-controller, policy-engine, and router) follow the [12-factor app](https://12factor.net/logs) architecture principle for logging: @@ -50,13 +50,13 @@ The default logging stack consists of: This architecture approach allows you to utilize **any industry-standard logging stack** to collect logs from Docker container log files and view them in your preferred observability platform. The gateway components are completely decoupled from the logging infrastructure. -### Demonstrated Logging Services +### Demonstrated logging services The logging services included in the Docker Compose file (OpenSearch, OpenSearch Dashboards, and Fluent Bit) are provided as **demonstration services** to show one possible way to collect and visualize logs. You can use them as-is for development/testing, or replace them with your own logging solution. The gateway uses Docker Compose profiles to optionally enable these demonstration logging services. -### Start Gateway with Demonstrated Logging Services +### Start gateway with demonstrated logging services To start the gateway with the demonstration logging services enabled: @@ -70,7 +70,7 @@ This starts: - OpenSearch Dashboards - *web UI for viewing logs* - Fluent Bit - *collects logs from Docker and forwards to OpenSearch* -### Start Gateway without Logging Services +### Start gateway without logging services To run only the core gateway services without the demonstration logging stack: @@ -86,7 +86,7 @@ docker logs policy-engine docker logs router ``` -### Stop Logging Services +### Stop logging services To stop all services including the logging stack: @@ -102,7 +102,7 @@ docker compose --profile logging down -v This removes the `opensearch-data` volume containing all stored logs. -## Viewing Logs in OpenSearch Dashboards +## Viewing logs in OpenSearch Dashboards Once you've started the gateway with the logging profile, follow these steps to view component logs: @@ -113,7 +113,7 @@ Open your browser and navigate to: http://localhost:5601 ``` -### Step 2: Create an Index Pattern +### Step 2: Create an index pattern Before you can view logs, you need to create an index pattern: @@ -126,7 +126,7 @@ Before you can view logs, you need to create an index pattern: 7. Select **@timestamp** as the time field 8. Click **Create index pattern** -### Step 3: Navigate to Discover +### Step 3: Navigate to discover To view and explore logs: @@ -135,11 +135,11 @@ To view and explore logs: 3. Select the `gateway-logs-*` index pattern from the dropdown in the top-left 4. Adjust the time range in the top-right corner if needed (default is last 15 minutes) -### Step 4: Filter Logs by Component +### Step 4: Filter logs by component To view logs for a specific gateway component, use filters: -#### View Policy Engine Logs +#### View policy engine logs 1. Click **Add filter** (below the search bar) 2. **Field**: Select `component` @@ -147,7 +147,7 @@ To view logs for a specific gateway component, use filters: 4. **Value**: Enter `policy-engine` 5. Click **Save** -#### View Gateway Controller Logs +#### View gateway controller logs 1. Click **Add filter** 2. **Field**: `component` @@ -155,7 +155,7 @@ To view logs for a specific gateway component, use filters: 4. **Value**: `gateway-controller` 5. Click **Save** -#### View Router (Envoy) Logs +#### View router (envoy) logs 1. Click **Add filter** 2. **Field**: `component` @@ -163,11 +163,11 @@ To view logs for a specific gateway component, use filters: 4. **Value**: `router` 5. Click **Save** -### Step 5: Search and Filter Logs +### Step 5: Search and filter logs You can refine your log search using: -#### Free Text Search +#### Free text search Enter keywords in the search bar at the top: ``` error @@ -176,19 +176,19 @@ error Weather-API ``` -#### Filter by Log Level +#### Filter by log level 1. Click **Add filter** 2. **Field**: `level` 3. **Operator**: `is` 4. **Value**: `error` (or `info`, `warn`, `debug`) -#### Combine Multiple Filters +#### Combine multiple filters Add multiple filters to narrow down results. For example: - Component: `policy-engine` - Level: `error` - Time range: Last 1 hour -#### Example Search Queries +#### Example search queries Search for errors in the policy engine: ``` @@ -205,18 +205,18 @@ Search for slow requests (if duration field exists): duration_ms:>1000 ``` -### Step 6: Customize Log View +### Step 6: Customize log view -- **Add/Remove Columns**: Click the **gear icon** next to the field list to select which fields to display +- **Add/remove columns**: Click the **gear icon** next to the field list to select which fields to display - **Sort**: Click column headers to sort by that field -- **Expand Logs**: Click the **>** arrow next to any log entry to see full details in JSON format -- **Save Search**: Click **Save** in the top menu to save your filters and queries for later use +- **Expand logs**: Click the **>** arrow next to any log entry to see full details in JSON format +- **Save search**: Click **Save** in the top menu to save your filters and queries for later use -## Alternative Logging Stacks +## Alternative logging stacks While the default setup uses OpenSearch and Fluent Bit, you can integrate with other logging platforms: -### Elastic Stack (ELK) +### Elastic stack (ELK) Replace OpenSearch with the Elastic Stack: @@ -286,7 +286,7 @@ grafana: - loki ``` -### Cloud-Native Solutions +### Cloud-native solutions #### AWS CloudWatch @@ -339,7 +339,7 @@ Configure Fluent Bit to forward to Splunk HEC: ``` -## Additional Resources +## Additional resources - [Fluent Bit Documentation](https://docs.fluentbit.io/) - [OpenSearch Documentation](https://opensearch.org/docs/latest/) diff --git a/en/docs/api-gateway/observability/metrics/alternative-backends.md b/en/docs/api-gateway/observability/metrics/alternative-backends.md index 2fe3b4d4..eda497ef 100644 --- a/en/docs/api-gateway/observability/metrics/alternative-backends.md +++ b/en/docs/api-gateway/observability/metrics/alternative-backends.md @@ -1,5 +1,5 @@ --- -title: "Export Metrics to Alternative Backends" +title: "Export metrics to alternative backends" description: "Export API Platform Gateway metrics to alternative backends including AWS CloudWatch, Datadog, and other Prometheus-compatible systems." canonical_url: https://wso2.com/api-platform/docs/api-gateway/observability/metrics/alternative-backends/ md_url: https://wso2.com/api-platform/docs/api-gateway/observability/metrics/alternative-backends.md @@ -12,11 +12,11 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# Alternative Metrics Backends +# Alternative metrics backends While the default setup uses Prometheus and Grafana, the gateway components expose standard Prometheus metrics and can integrate with any Prometheus-compatible system. -## AWS CloudWatch +## AWS cloudwatch Use AWS Distro for OpenTelemetry (ADOT) to export metrics to CloudWatch: @@ -60,7 +60,7 @@ instances: - policy_engine_* ``` -## New Relic +## New relic Use New Relic's Prometheus remote write integration: @@ -100,7 +100,7 @@ metricbeat: Configure Metricbeat to scrape Prometheus endpoints. -## Azure Monitor +## Azure monitor Use Azure Monitor Agent with Prometheus scraping: @@ -113,7 +113,7 @@ azuremonitor-agent: - AZURE_CLIENT_SECRET=${AZURE_CLIENT_SECRET} ``` -## Google Cloud Monitoring +## Google cloud monitoring Use Cloud Monitoring Prometheus sidecar: @@ -126,7 +126,7 @@ prometheus-to-monitoring: - ./key.json:/var/secrets/google/key.json:ro ``` -## Grafana Cloud +## Grafana cloud Use Prometheus remote write to Grafana Cloud: diff --git a/en/docs/api-gateway/observability/metrics/best-practices-and-troubleshooting.md b/en/docs/api-gateway/observability/metrics/best-practices-and-troubleshooting.md index ceba9c85..da7cb5e4 100644 --- a/en/docs/api-gateway/observability/metrics/best-practices-and-troubleshooting.md +++ b/en/docs/api-gateway/observability/metrics/best-practices-and-troubleshooting.md @@ -1,5 +1,5 @@ --- -title: "Metrics Best Practices and Troubleshooting" +title: "Metrics best practices and troubleshooting" description: "Best practices for correlating API Platform Gateway metrics with logs and traces, and guidance for troubleshooting common metrics issues." canonical_url: https://wso2.com/api-platform/docs/api-gateway/observability/metrics/best-practices-and-troubleshooting/ md_url: https://wso2.com/api-platform/docs/api-gateway/observability/metrics/best-practices-and-troubleshooting.md @@ -13,31 +13,31 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# Best Practices and Troubleshooting +# Best practices and troubleshooting -## Integration with Logging and Tracing +## Integration with logging and tracing Metrics, logs, and traces work together for comprehensive observability: -### Correlating Metrics with Logs +### Correlating metrics with logs 1. **Correlation IDs**: Gateway components include request IDs in both logs and metrics -2. **Find Logs from Metrics**: Use metric labels to filter logs (e.g., API name, route) -3. **Find Metrics from Logs**: Copy request IDs from logs and query metrics with labels +2. **Find logs from metrics**: Use metric labels to filter logs (e.g., API name, route) +3. **Find metrics from logs**: Copy request IDs from logs and query metrics with labels Example: If you see errors in logs for a specific API, query metrics for that API: ```promql gateway_controller_api_operations_total{api_name="Weather-API", status="failure"} ``` -### Correlating Metrics with Traces +### Correlating metrics with traces Metrics and traces share labels for correlation: - Trace IDs are included in log entries - You can search traces by API name or route - Span attributes include metric labels -### Using All Three Stacks +### Using all three stacks Enable all observability profiles: ```bash @@ -49,7 +49,7 @@ This provides: - **Traces**: Request flow and performance debugging - **Logs**: Detailed event information and error context -## Best Practices +## Best practices ### Development - Use default scrape interval (15s) for reasonable granularity @@ -106,7 +106,7 @@ This provides: - **Prune unused metrics** to reduce cardinality - **Compress metric names** to reduce storage -### Metric Cardinality +### Metric cardinality Avoid high-cardinality labels (millions of unique values): @@ -120,7 +120,7 @@ gateway_controller_api_operations_total{route="/weather/v1"} gateway_controller_api_operations_total{user_id="12345"} ``` -### Query Optimization +### Query optimization **Use time ranges**: ```promql @@ -142,7 +142,7 @@ rate(gateway_controller_http_request_duration_seconds_sum[5m]) ## Troubleshooting -### Metrics Not Appearing in Grafana +### Metrics not appearing in Grafana **1. Verify metrics are enabled in configuration:** ```bash @@ -187,7 +187,7 @@ docker exec prometheus wget -O- gateway-controller:9091/metrics docker exec prometheus wget -O- policy-engine:9003/metrics ``` -### High Cardinality Metrics +### High cardinality metrics **Symptoms:** - Prometheus memory usage constantly increasing @@ -205,7 +205,7 @@ curl http://localhost:9091/metrics | wc -l # Count metric lines - Use histogram buckets instead of labels - Aggregate before labeling -### Missing Metrics +### Missing metrics **1. Check if metric name changed** (after component update) ```bash @@ -224,7 +224,7 @@ docker logs gateway-controller | grep -i metric docker logs policy-engine | grep -i metric ``` -### Grafana Dashboards Not Loading +### Grafana dashboards not loading **1. Verify Grafana is running:** ```bash @@ -250,7 +250,7 @@ docker logs grafana # Upload JSON files from ./observability/grafana/dashboards/ ``` -### High Memory Usage +### High memory usage **1. Check Prometheus memory usage:** ```bash @@ -277,7 +277,7 @@ command: **5. Use Thanos or remote write** for long-term storage -### Slow Queries +### Slow queries **1. Identify slow queries:** ```promql @@ -303,7 +303,7 @@ prometheus: cpus: '2' ``` -### Metric Values Not Updating +### Metric values not updating **1. Check if metrics are counters with rate:** ```promql diff --git a/en/docs/api-gateway/observability/metrics/configuration.md b/en/docs/api-gateway/observability/metrics/configuration.md index ee5520a8..8cdbdbc9 100644 --- a/en/docs/api-gateway/observability/metrics/configuration.md +++ b/en/docs/api-gateway/observability/metrics/configuration.md @@ -1,5 +1,5 @@ --- -title: "Metrics Configuration Options" +title: "Metrics configuration options" description: "Configure Prometheus scrape intervals and custom metrics endpoints for API Platform Gateway components." canonical_url: https://wso2.com/api-platform/docs/api-gateway/observability/metrics/configuration/ md_url: https://wso2.com/api-platform/docs/api-gateway/observability/metrics/configuration.md @@ -12,9 +12,9 @@ last_updated: 2026-06-17 content_type: "reference" --- -# Configuration Options +# Configuration options -## Adjusting Scrape Interval +## Adjusting scrape interval To reduce metrics collection overhead or increase granularity, adjust the Prometheus scrape interval: @@ -31,7 +31,7 @@ Restart Prometheus after changes: docker compose restart prometheus ``` -## Custom Metrics Endpoints +## Custom metrics endpoints You can add additional metrics endpoints to scrape from: @@ -44,7 +44,7 @@ scrape_configs: scrape_interval: 30s ``` -## Metric Retention +## Metric retention Configure how long Prometheus retains metrics: @@ -57,17 +57,17 @@ command: - '--storage.tsdb.retention.size=10GB' # Keep up to 10GB of metrics ``` -## Custom Bucket Configuration +## Custom bucket configuration Gateway components use optimized bucket configurations for histograms: -**Request Duration Buckets**: +**Request duration buckets**: - Gateway Controller: `[0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0]` - Policy Engine: `[0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5]` -**Policy Execution Buckets**: +**Policy execution buckets**: - `[0.0001, 0.0005, 0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5]` -**Deployment Latency Buckets**: +**Deployment latency buckets**: - `[0.1, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0, 60.0]` diff --git a/en/docs/api-gateway/observability/metrics/enabling-metrics.md b/en/docs/api-gateway/observability/metrics/enabling-metrics.md index 04438a08..afb89b63 100644 --- a/en/docs/api-gateway/observability/metrics/enabling-metrics.md +++ b/en/docs/api-gateway/observability/metrics/enabling-metrics.md @@ -1,5 +1,5 @@ --- -title: "Enable Metrics" +title: "Enable metrics" description: "Enable and configure Prometheus metrics collection for API Platform Gateway components in config.toml." canonical_url: https://wso2.com/api-platform/docs/api-gateway/observability/metrics/enabling-metrics/ md_url: https://wso2.com/api-platform/docs/api-gateway/observability/metrics/enabling-metrics.md @@ -13,17 +13,17 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# Enabling and Disabling Metrics +# Enabling and disabling metrics -## Enabling Metrics +## Enabling metrics -### Configuration Required +### Configuration required You need to enable metrics in the gateway configuration file. By default, metrics are enabled in the production configuration but you can customize the settings. The metrics configuration is located in `gateway/configs/config.toml`: -#### Gateway Controller Metrics Configuration +#### Gateway controller metrics configuration ```toml [controller.metrics] @@ -34,7 +34,7 @@ enabled = true port = 9091 ``` -#### Policy Engine Metrics Configuration +#### Policy engine metrics configuration ```toml [policy_engine.metrics] @@ -47,15 +47,15 @@ port = 9003 **Note**: When metrics are enabled, each component starts an HTTP server on the specified port to expose metrics in Prometheus format. -### Demonstrated Metrics Services +### Demonstrated metrics services The metrics services included in the Docker Compose file (Prometheus and Grafana) are provided as **demonstration services** to show one possible way to collect and visualize metrics. You can use them as-is for development/testing, or replace them with your own metrics solution. The gateway uses Docker Compose profiles to optionally enable these demonstration metrics services. -#### Setting up Grafana Image +#### Setting up Grafana image -**Important Note:** The Grafana image in the `docker-compose.yaml` file is intentionally left empty due to licensing considerations. Before you can use the demonstration dashboards, you must specify a valid Grafana image. +**Important note:** The Grafana image in the `docker-compose.yaml` file is intentionally left empty due to licensing considerations. Before you can use the demonstration dashboards, you must specify a valid Grafana image. To add the Grafana image: @@ -69,7 +69,7 @@ To add the Grafana image: container_name: grafana ``` -### Start Gateway with Demonstrated Metrics Services +### Start gateway with demonstrated metrics services To start the gateway with the demonstration metrics services enabled: @@ -82,7 +82,7 @@ This starts: - Prometheus - *scrapes and stores metrics* - Grafana - *visualizes metrics through dashboards* -### Start Gateway without Metrics Services +### Start gateway without metrics services To run only the core gateway services without the demonstration metrics stack: @@ -95,7 +95,7 @@ docker compose up -d - Policy Engine: - Router (Envoy): -### Stop Metrics Services +### Stop metrics services To stop all services including the metrics stack: @@ -111,7 +111,7 @@ docker compose --profile metrics down -v This removes the `prometheus-data` volume containing all stored metrics. -## Disabling Metrics +## Disabling metrics To completely disable metrics: diff --git a/en/docs/api-gateway/observability/metrics/metric-reference.md b/en/docs/api-gateway/observability/metrics/metric-reference.md index 7bc27b74..a6cf2cd5 100644 --- a/en/docs/api-gateway/observability/metrics/metric-reference.md +++ b/en/docs/api-gateway/observability/metrics/metric-reference.md @@ -1,5 +1,5 @@ --- -title: "Metric Reference" +title: "Metric reference" description: "Complete reference for all Prometheus metrics exposed by API Platform Gateway controller, router, and policy engine components." canonical_url: https://wso2.com/api-platform/docs/api-gateway/observability/metrics/metric-reference/ md_url: https://wso2.com/api-platform/docs/api-gateway/observability/metrics/metric-reference.md @@ -12,11 +12,11 @@ last_updated: 2026-06-17 content_type: "reference" --- -# Metric Reference +# Metric reference -## Gateway Controller Metrics +## Gateway controller metrics -### API Management +### API management - `gateway_controller_api_operations_total`: Counter of API operations - Labels: `operation`, `status`, `api_type` - `gateway_controller_api_operation_duration_seconds`: Histogram of operation duration @@ -27,7 +27,7 @@ content_type: "reference" - Labels: `operation`, `error_type` - `gateway_controller_deployment_latency_seconds`: Histogram of deployment latency -### xDS Metrics +### xDS metrics - `gateway_controller_xds_clients_connected`: Gauge of connected xDS clients - Labels: `server`, `node_id` - `gateway_controller_snapshot_generation_duration_seconds`: Histogram of snapshot generation time @@ -41,7 +41,7 @@ content_type: "reference" - `gateway_controller_xds_snapshot_ack_total`: Counter of snapshot ACK/NACK - Labels: `server`, `node_id`, `status` -### Database Metrics +### Database metrics - `gateway_controller_database_operations_total`: Counter of database operations - Labels: `operation`, `table`, `status` - `gateway_controller_database_operation_duration_seconds`: Histogram of operation duration @@ -51,7 +51,7 @@ content_type: "reference" - `gateway_controller_config_store_size`: Gauge of config store items - Labels: `type` -### HTTP API Metrics +### HTTP API metrics - `gateway_controller_http_requests_total`: Counter of HTTP requests - Labels: `method`, `endpoint`, `status_code` - `gateway_controller_http_request_duration_seconds`: Histogram of request duration @@ -62,7 +62,7 @@ content_type: "reference" - Labels: `endpoint` - `gateway_controller_concurrent_requests`: Gauge of concurrent requests -### System Metrics +### System metrics - `gateway_controller_up`: Gauge of component liveness (1=up, 0=down) - `gateway_controller_info`: Gauge of build information - Labels: `version`, `storage_type`, `build_date` @@ -70,7 +70,7 @@ content_type: "reference" - `gateway_controller_memory_bytes`: Gauge of memory usage - Labels: `type` (heap_alloc, heap_sys, stack_inuse) -### Error Metrics +### Error metrics - `gateway_controller_errors_total`: Counter of errors - Labels: `component`, `error_type` - `gateway_controller_panic_recoveries_total`: Counter of panic recoveries @@ -80,7 +80,7 @@ content_type: "reference" - `gateway_controller_translation_errors_total`: Counter of translation errors - Labels: `error_type` -### Certificate Metrics +### Certificate metrics - `gateway_controller_certificates_total`: Gauge of certificates - Labels: `type` - `gateway_controller_certificate_operations_total`: Counter of certificate operations @@ -88,7 +88,7 @@ content_type: "reference" - `gateway_controller_certificate_expiry_seconds`: Gauge of certificate expiry - Labels: `cert_id`, `cert_name` -### Policy Metrics +### Policy metrics - `gateway_controller_policies_total`: Gauge of policies - Labels: `api_id`, `route` - `gateway_controller_policy_chain_length`: Histogram of policy chain length @@ -98,9 +98,9 @@ content_type: "reference" - `gateway_controller_policy_validation_errors_total`: Counter of validation errors - Labels: `error_type` -## Policy Engine Metrics +## Policy engine metrics -### Request Processing +### Request processing - `policy_engine_requests_total`: Counter of processed requests - Labels: `phase` (request, response), `route`, `api_name`, `api_version` - `policy_engine_request_duration_seconds`: Histogram of request duration @@ -110,7 +110,7 @@ content_type: "reference" - `policy_engine_short_circuits_total`: Counter of short-circuited requests - Labels: `route`, `policy_name` -### Policy Execution +### Policy execution - `policy_engine_policy_executions_total`: Counter of policy executions - Labels: `policy_name`, `policy_version`, `api`, `route`, `status` - `policy_engine_policy_duration_seconds`: Histogram of policy execution duration @@ -139,13 +139,13 @@ content_type: "reference" - `policy_engine_grpc_connections_active`: Gauge of active gRPC connections - Labels: `type` -### System Metrics +### System metrics - `policy_engine_up`: Gauge of component liveness (1=up, 0=down) - `policy_engine_goroutines`: Gauge of current goroutines - `policy_engine_memory_bytes`: Gauge of memory usage - Labels: `type` (heap_alloc, heap_sys, stack) -### Error Metrics +### Error metrics - `policy_engine_policy_errors_total`: Counter of policy errors - Labels: `policy_name`, `error_type` - `policy_engine_stream_errors_total`: Counter of stream errors @@ -154,29 +154,29 @@ content_type: "reference" - `policy_engine_panic_recoveries_total`: Counter of panic recoveries - Labels: `component` -## Router (Envoy) Metrics +## Router (envoy) metrics Envoy exposes built-in Prometheus metrics. Key metrics include: -### HTTP Metrics +### HTTP metrics - `envoy_http_internal_requests_total`: Counter of HTTP requests - Labels: `virtual_cluster`, `virtual_host`, `response_code` - `envoy_http_request_duration_seconds`: Histogram of request duration - `envoy_http_downstream_cx_active`: Gauge of active connections - `envoy_http_downstream_cx_total`: Counter of connections -### Upstream Metrics +### Upstream metrics - `envoy_http_upstream_rq_total`: Counter of upstream requests - Labels: `upstream_cluster`, `response_code` - `envoy_http_upstream_rq_xx`: Counter of upstream requests by status - Labels: `upstream_cluster`, `envoy_response_flags` -### Cluster Metrics +### Cluster metrics - `envoy_cluster_upstream_cx_active`: Gauge of active upstream connections - `envoy_cluster_upstream_rq_retry_total`: Counter of retry requests - `envoy_cluster_membership_healthy`: Gauge of healthy endpoints -### Listener Metrics +### Listener metrics - `envoy_listener_downstream_cx_active`: Gauge of active downstream connections - `envoy_listener_downstream_cx_total`: Counter of downstream connections diff --git a/en/docs/api-gateway/observability/metrics/overview.md b/en/docs/api-gateway/observability/metrics/overview.md index 2c30ef46..53c32a3d 100644 --- a/en/docs/api-gateway/observability/metrics/overview.md +++ b/en/docs/api-gateway/observability/metrics/overview.md @@ -1,5 +1,5 @@ --- -title: "Gateway Metrics" +title: "Gateway metrics" description: "Configure metrics collection for API Platform Gateway components using Prometheus and Grafana, with reference dashboards and alerting." canonical_url: https://wso2.com/api-platform/docs/api-gateway/observability/metrics/ md_url: https://wso2.com/api-platform/docs/api-gateway/observability/metrics/overview.md @@ -12,7 +12,7 @@ last_updated: 2026-06-11 content_type: "how-to" --- -# Gateway Metrics +# Gateway metrics This guide explains how to implement and configure metrics collection for the API Platform Gateway components. @@ -22,14 +22,14 @@ The default metrics services included in the Docker Compose configuration are ** **Important**: You are free to choose any metrics or observability strategy that suits your environment and requirements. The provided setup is just one of many possible configurations. -## Metrics Architecture +## Metrics architecture The default metrics stack consists of: - **Prometheus**: Scrapes, stores, and queries metrics from gateway components - **Grafana**: Visualizes metrics through dashboards with alerts and notifications -### How It Works +### How it works 1. Gateway components (gateway-controller, policy-engine, router) expose metrics via Prometheus HTTP endpoints 2. Prometheus scrapes these endpoints at regular intervals (default: 15s) @@ -37,7 +37,7 @@ The default metrics stack consists of: 4. Grafana queries Prometheus to visualize metrics through pre-built dashboards 5. Users can view real-time metrics, historical trends, and set up alerts -### What are Metrics? +### What are metrics? Metrics are numerical measurements tracked over time: @@ -45,7 +45,7 @@ Metrics are numerical measurements tracked over time: - **Gauges**: Current values that can go up or down (e.g., active connections, memory usage) - **Histograms**: Sample observations with configurable buckets (e.g., request duration) -## In This Section +## In this section - [Enabling and Disabling Metrics](enabling-metrics.md) — Turn metrics on or off and run the demonstration metrics services - [Viewing Metrics in Grafana](viewing-metrics-in-grafana.md) — Explore pre-built dashboards, create custom dashboards, and set up alerts @@ -55,7 +55,7 @@ Metrics are numerical measurements tracked over time: - [Metric Reference](metric-reference.md) — Full list of metrics exposed by each gateway component - [Best Practices and Troubleshooting](best-practices-and-troubleshooting.md) — Recommendations, common issues, and integration with logging and tracing -## Additional Resources +## Additional resources - [Prometheus Documentation](https://prometheus.io/docs/) - [Grafana Documentation](https://grafana.com/docs/) diff --git a/en/docs/api-gateway/observability/metrics/prometheus-queries.md b/en/docs/api-gateway/observability/metrics/prometheus-queries.md index 128d8217..617ad005 100644 --- a/en/docs/api-gateway/observability/metrics/prometheus-queries.md +++ b/en/docs/api-gateway/observability/metrics/prometheus-queries.md @@ -1,5 +1,5 @@ --- -title: "Prometheus Queries" +title: "Prometheus queries" description: "Useful PromQL queries for monitoring API Platform Gateway controller, router, and policy engine metrics." canonical_url: https://wso2.com/api-platform/docs/api-gateway/observability/metrics/prometheus-queries/ md_url: https://wso2.com/api-platform/docs/api-gateway/observability/metrics/prometheus-queries.md @@ -13,96 +13,96 @@ last_updated: 2026-06-17 content_type: "reference" --- -# Prometheus Queries +# Prometheus queries You can query Prometheus directly at to create custom visualizations or debug issues. -## Useful Queries +## Useful queries -### Gateway Controller +### Gateway controller -**Total API Operations**: +**Total API operations**: ```promql rate(gateway_controller_api_operations_total[5m]) ``` -**API Operations by Status**: +**API operations by status**: ```promql rate(gateway_controller_api_operations_total[5m]) by (status) ``` -**Deployment Latency Percentiles**: +**Deployment latency percentiles**: ```promql histogram_quantile(0.95, rate(gateway_controller_deployment_latency_seconds_bucket[5m])) ``` -**xDS Clients Connected**: +**xDS clients connected**: ```promql gateway_controller_xds_clients_connected ``` -**Database Operation Rate**: +**Database operation rate**: ```promql rate(gateway_controller_database_operations_total[5m]) ``` -**Memory Usage**: +**Memory usage**: ```promql gateway_controller_memory_bytes ``` -**HTTP Request Duration**: +**HTTP request duration**: ```promql histogram_quantile(0.99, rate(gateway_controller_http_request_duration_seconds_bucket[5m])) ``` -### Policy Engine +### Policy engine -**Request Rate**: +**Request rate**: ```promql rate(policy_engine_requests_total[5m]) ``` -**Policy Execution Rate**: +**Policy execution rate**: ```promql rate(policy_engine_policy_executions_total[5m]) ``` -**Policy Execution Success Rate**: +**Policy execution success rate**: ```promql rate(policy_engine_policy_executions_total{status="success"}[5m]) / rate(policy_engine_policy_executions_total[5m]) ``` -**Average Request Duration**: +**Average request duration**: ```promql rate(policy_engine_request_duration_seconds_sum[5m]) / rate(policy_engine_request_duration_seconds_count[5m]) ``` -**Active Streams**: +**Active streams**: ```promql policy_engine_active_streams ``` -**Error Rate**: +**Error rate**: ```promql rate(policy_engine_request_errors_total[5m]) ``` -### Router (Envoy) +### Router (envoy) -**Request Rate**: +**Request rate**: ```promql rate(envoy_http_internal_requests_total[5m]) ``` -**Request Duration**: +**Request duration**: ```promql histogram_quantile(0.99, rate(envoy_http_request_duration_seconds_bucket[5m])) ``` -**Upstream 5xx Errors**: +**Upstream 5xx errors**: ```promql rate(envoy_http_upstream_rq_xx{envoy_response_flags="upstream_connect_fail"}[5m]) ``` diff --git a/en/docs/api-gateway/observability/metrics/viewing-metrics-in-grafana.md b/en/docs/api-gateway/observability/metrics/viewing-metrics-in-grafana.md index 3902a07e..f16dcb46 100644 --- a/en/docs/api-gateway/observability/metrics/viewing-metrics-in-grafana.md +++ b/en/docs/api-gateway/observability/metrics/viewing-metrics-in-grafana.md @@ -1,5 +1,5 @@ --- -title: "View Metrics in Grafana" +title: "View metrics in Grafana" description: "Access pre-built Grafana dashboards to view and explore API Platform Gateway component metrics." canonical_url: https://wso2.com/api-platform/docs/api-gateway/observability/metrics/viewing-metrics-in-grafana/ md_url: https://wso2.com/api-platform/docs/api-gateway/observability/metrics/viewing-metrics-in-grafana.md @@ -13,7 +13,7 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# Viewing Metrics in Grafana +# Viewing metrics in Grafana Once you've started the gateway with the metrics profile, follow these steps to view component metrics: @@ -28,7 +28,7 @@ Open your browser and navigate to: **Note**: You'll be prompted to change the password on first login. -## Step 3: Navigate to Dashboards +## Step 3: Navigate to dashboards 1. Click on the **hamburger menu (☰)** in the top-left corner 2. Navigate to **Dashboards** → **Browse** @@ -37,33 +37,33 @@ Open your browser and navigate to: - **Gateway Controller**: Detailed gateway-controller metrics - **Policy Engine**: Detailed policy-engine metrics -## Step 4: View Infrastructure Overview +## Step 4: View infrastructure overview The Infrastructure Overview dashboard provides a comprehensive view: -### Gateway Controller Section +### Gateway controller section - **API Operations**: Total operations and operation rate - **Deployment Latency**: End-to-end deployment time - **xDS Clients**: Number of connected Envoy routers - **Database Operations**: Database operation metrics - **HTTP Requests**: REST API request metrics -### Policy Engine Section +### Policy engine section - **Request Processing**: Total requests and request rate - **Policy Executions**: Policy execution metrics - **Active Streams**: Current ext_proc streams - **Errors**: Error rate and types -### System Resources +### System resources - **Memory Usage**: Heap, system memory across components - **Goroutines**: Go runtime goroutines count - **Uptime**: Component availability -## Step 5: View Gateway Controller Dashboard +## Step 5: View gateway controller dashboard The Gateway Controller dashboard provides detailed metrics: -### API Management +### API management - **API Operations Total**: Counter for all API operations with labels for: - `operation`: create, update, delete, get - `status`: success, failure @@ -71,27 +71,27 @@ The Gateway Controller dashboard provides detailed metrics: - **APIs Total**: Gauge showing deployed APIs by type and status - **Deployment Latency Seconds**: Histogram of deployment times -### xDS Metrics +### xDS metrics - **xDS Clients Connected**: Gauge of connected Envoy instances - **Snapshot Generation Duration**: Time to generate configuration snapshots - **XDS Stream Requests**: Counter for xDS requests by type - **Snapshot Size**: Size of generated configuration snapshots -### Database Metrics +### Database metrics - **Database Operations Total**: Counter for database operations - **Database Operation Duration**: Histogram of operation times - **Database Size Bytes**: Current database size -### HTTP API Metrics +### HTTP API metrics - **HTTP Requests Total**: Counter for REST API requests - **HTTP Request Duration**: Histogram of API response times - **Concurrent Requests**: Current concurrent API requests -## Step 6: View Policy Engine Dashboard +## Step 6: View policy engine dashboard The Policy Engine dashboard provides detailed metrics: -### Request Processing +### Request processing - **Requests Total**: Counter for all processed requests with labels: - `phase`: request, response - `route`: route name @@ -100,7 +100,7 @@ The Policy Engine dashboard provides detailed metrics: - **Request Duration Seconds**: Histogram of request processing times - **Request Errors Total**: Counter for errors by type -### Policy Execution +### Policy execution - **Policy Executions Total**: Counter for policy executions with labels: - `policy_name`: Name of executed policy - `policy_version`: Policy version @@ -115,12 +115,12 @@ The Policy Engine dashboard provides detailed metrics: - **XDS Updates Total**: Counter for configuration updates - **Body Bytes Processed**: Counter for body processing -### System Resources +### System resources - **Memory Usage**: Memory consumption metrics - **Goroutines**: Current goroutines count - **GRPC Connections**: Active gRPC connections -## Step 7: Create Custom Dashboards +## Step 7: Create custom dashboards You can create custom dashboards in Grafana: @@ -131,7 +131,7 @@ You can create custom dashboards in Grafana: 5. Configure visualization (graphs, tables, gauges, etc.) 6. Save the dashboard -## Step 8: Set Up Alerts +## Step 8: Set up alerts Create alerts to be notified of issues: diff --git a/en/docs/api-gateway/observability/tracing/alternative-backends.md b/en/docs/api-gateway/observability/tracing/alternative-backends.md index 12e79eb6..a4537f43 100644 --- a/en/docs/api-gateway/observability/tracing/alternative-backends.md +++ b/en/docs/api-gateway/observability/tracing/alternative-backends.md @@ -1,5 +1,5 @@ --- -title: "Export Traces to Alternative Backends" +title: "Export traces to alternative backends" description: "Configure API Platform Gateway to export OpenTelemetry traces to alternative backends including Moesif, Datadog, and New Relic." canonical_url: https://wso2.com/api-platform/docs/api-gateway/observability/tracing/alternative-backends/ md_url: https://wso2.com/api-platform/docs/api-gateway/observability/tracing/alternative-backends.md @@ -12,7 +12,7 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# Alternative Tracing Backends +# Alternative tracing backends While the default setup uses Jaeger, the gateway components use OpenTelemetry and can export to any OTLP-compatible backend. @@ -42,12 +42,12 @@ service: exporters: [otlphttp] # Send to Moesif ``` -**Important Notes:** +**Important notes:** - The endpoint uses HTTPS (not HTTP) - Use the `otlphttp` exporter (not `otlp` which uses gRPC) - The `X-Moesif-Application-Id` header is required for authentication -### Obtaining Your Moesif Application ID +### Obtaining your Moesif application ID 1. Sign up for a Moesif account at [moesif.com](https://www.moesif.com) 2. Log in to your Moesif dashboard @@ -55,7 +55,7 @@ service: 4. Locate the **Collector Application ID** field 5. Copy your unique Application ID -### Using Environment Variables +### Using environment variables For better security, use environment variables for the Application ID: @@ -84,7 +84,7 @@ export MOESIF_APPLICATION_ID=your-moesif-application-id docker compose --profile tracing up -d ``` -### Accessing Moesif Dashboard +### Accessing Moesif dashboard After configuring and starting the gateway: @@ -94,16 +94,16 @@ After configuring and starting the gateway: 4. Use **Time Series** to analyze API usage trends 5. Set up **Alerts** for error rates, latency, or custom conditions -### Moesif Features +### Moesif features - **API Analytics**: Request volume, response times, error rates -- **User Tracking**: Identify and track API users across requests -- **Error Analysis**: Detailed error tracking with request/response bodies -- **Behavioral Cohorts**: Group users by API usage patterns -- **Custom Dashboards**: Build visualizations for your specific KPIs +- **User tracking**: Identify and track API users across requests +- **Error analysis**: Detailed error tracking with request/response bodies +- **Behavioral cohorts**: Group users by API usage patterns +- **Custom dashboards**: Build visualizations for your specific KPIs - **Alerting**: Get notified of anomalies or threshold breaches -### Sending to Both Jaeger and Moesif +### Sending to both Jaeger and Moesif You can send traces to both Jaeger (for development) and Moesif (for analytics): @@ -152,7 +152,7 @@ exporters: Access Zipkin UI at `http://localhost:9411` -## Grafana Tempo +## Grafana tempo For a Prometheus-style tracing backend: @@ -190,7 +190,7 @@ tracing: endpoint: tempo:4317 ``` -## Cloud-Native Tracing Solutions +## Cloud-native tracing solutions ### AWS X-Ray @@ -213,7 +213,7 @@ otel-collector: - AWS_REGION=us-east-1 ``` -### Google Cloud Trace +### Google cloud trace Configure OTLP Collector to export to Google Cloud: @@ -224,7 +224,7 @@ exporters: use_insecure: false ``` -### Azure Monitor +### Azure monitor Use Azure Monitor exporter: @@ -268,7 +268,7 @@ tracing: endpoint: datadog-agent:4317 ``` -### New Relic +### New relic Configure OTLP Collector to export to New Relic: @@ -300,7 +300,7 @@ exporters: lightstep-access-token: ${LIGHTSTEP_ACCESS_TOKEN} ``` -## Service Mesh Integration +## Service mesh integration If using a service mesh like Istio or Linkerd: diff --git a/en/docs/api-gateway/observability/tracing/best-practices-and-troubleshooting.md b/en/docs/api-gateway/observability/tracing/best-practices-and-troubleshooting.md index f1096c71..c0ef6ccf 100644 --- a/en/docs/api-gateway/observability/tracing/best-practices-and-troubleshooting.md +++ b/en/docs/api-gateway/observability/tracing/best-practices-and-troubleshooting.md @@ -1,5 +1,5 @@ --- -title: "Tracing Best Practices and Troubleshooting" +title: "Tracing best practices and troubleshooting" description: "Best practices for distributed tracing in API Platform Gateway: sampling strategies, production recommendations, and troubleshooting guidance." canonical_url: https://wso2.com/api-platform/docs/api-gateway/observability/tracing/best-practices-and-troubleshooting/ md_url: https://wso2.com/api-platform/docs/api-gateway/observability/tracing/best-practices-and-troubleshooting.md @@ -13,9 +13,9 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# Best Practices and Troubleshooting +# Best practices and troubleshooting -## Best Practices +## Best practices ### Development - Use 100% sampling rate (`sampling_rate: 1.0`) @@ -46,7 +46,7 @@ content_type: "how-to" - Use asynchronous trace export (default with OTLP) - Consider using tail-based sampling for high-volume environments -### Sampling Strategy +### Sampling strategy Choose sampling based on traffic volume: @@ -61,7 +61,7 @@ Choose sampling based on traffic volume: ## Troubleshooting -### Traces Not Appearing in Jaeger +### Traces not appearing in Jaeger **1. Verify tracing is enabled in configuration:** ```bash @@ -100,14 +100,14 @@ docker logs policy-engine | grep -i trace docker logs gateway-controller | grep -i trace ``` -### Traces Are Incomplete or Missing Spans +### Traces are incomplete or missing spans **1. Check sampling rate** - ensure it's not too low **2. Verify all components are configured** to export traces **3. Check for trace context propagation issues** - ensure headers are preserved **4. Look for timeout errors** in OTLP collector logs -### High Trace Export Overhead +### High trace export overhead **1. Reduce sampling rate:** ```toml @@ -124,13 +124,13 @@ max_export_batch_size = 2048 **3. Use tail-based sampling** in OTLP collector to sample only important traces -### Traces Have Incorrect Timing +### Traces have incorrect timing - **Ensure system clocks are synchronized** across all containers (use NTP) - **Check for clock skew** in trace timeline view - **Verify trace context propagation** is working correctly -### Cannot Access Jaeger UI +### Cannot access Jaeger UI **1. Verify Jaeger is running:** ```bash @@ -147,15 +147,15 @@ docker logs jaeger curl http://localhost:16686/ ``` -## Integration with Logging +## Integration with logging Traces and logs work together for comprehensive observability: -### Correlating Traces and Logs +### Correlating traces and logs -1. **Trace ID in Logs**: Gateway components include trace IDs in log entries -2. **Find Trace from Log**: Copy trace ID from log entry and search in Jaeger -3. **Find Logs from Trace**: Copy trace ID from Jaeger and search in log viewer +1. **Trace ID in logs**: Gateway components include trace IDs in log entries +2. **Find trace from log**: Copy trace ID from log entry and search in Jaeger +3. **Find logs from trace**: Copy trace ID from Jaeger and search in log viewer Example log entry with trace ID: ```json @@ -169,7 +169,7 @@ Example log entry with trace ID: } ``` -### Using Both Stacks +### Using both stacks Enable both logging and tracing profiles: diff --git a/en/docs/api-gateway/observability/tracing/configuration.md b/en/docs/api-gateway/observability/tracing/configuration.md index 5a9bc81f..bdeda43f 100644 --- a/en/docs/api-gateway/observability/tracing/configuration.md +++ b/en/docs/api-gateway/observability/tracing/configuration.md @@ -1,5 +1,5 @@ --- -title: "Tracing Configuration Options" +title: "Tracing configuration options" description: "Configure distributed tracing for API Platform Gateway: sampling rates, OTLP collector endpoints, and batch export settings." canonical_url: https://wso2.com/api-platform/docs/api-gateway/observability/tracing/configuration/ md_url: https://wso2.com/api-platform/docs/api-gateway/observability/tracing/configuration.md @@ -12,11 +12,11 @@ last_updated: 2026-06-17 content_type: "reference" --- -# Tracing Configuration +# Tracing configuration -## Configuration Options +## Configuration options -### Adjusting Sampling Rate +### Adjusting sampling rate To reduce trace volume in high-traffic environments, adjust the sampling rate: @@ -34,7 +34,7 @@ Sampling strategies: **Note:** Lower sampling rates reduce overhead but may miss important traces. -### Custom Service Names +### Custom service names Customize service names for better identification: @@ -43,7 +43,7 @@ Customize service names for better identification: service_name = "policy-engine-prod-us-east-1" ``` -### Batch Configuration +### Batch configuration Optimize batch settings for your environment: @@ -63,7 +63,7 @@ The OTLP Collector configuration is located at: gateway/observability/otel-collector/config.yaml ``` -### Configuration Structure +### Configuration structure The configuration consists of three main sections: @@ -128,7 +128,7 @@ exporters: sampling_thereafter: 200 ``` -#### Service Pipeline +#### Service pipeline Connect receivers, processors, and exporters: ```yaml @@ -140,7 +140,7 @@ service: exporters: [otlp, debug] ``` -### Example: Multi-Backend Export +### Example: Multi-backend export Send traces to multiple backends simultaneously: @@ -168,7 +168,7 @@ service: exporters: [otlp/jaeger, otlp/tempo, datadog] ``` -### Example: Tail-Based Sampling +### Example: Tail-based sampling Keep all error traces but sample successful traces: @@ -190,7 +190,7 @@ processors: sampling_percentage: 10 ``` -## Trace Context Propagation +## Trace context propagation The gateway components automatically propagate trace context using standard W3C Trace Context headers: diff --git a/en/docs/api-gateway/observability/tracing/enabling-tracing.md b/en/docs/api-gateway/observability/tracing/enabling-tracing.md index 327ae76f..ed4fbaf7 100644 --- a/en/docs/api-gateway/observability/tracing/enabling-tracing.md +++ b/en/docs/api-gateway/observability/tracing/enabling-tracing.md @@ -1,5 +1,5 @@ --- -title: "Enable Distributed Tracing" +title: "Enable distributed tracing" description: "Enable and configure distributed tracing for API Platform Gateway in config.toml by pointing to an OTLP collector endpoint." canonical_url: https://wso2.com/api-platform/docs/api-gateway/observability/tracing/enabling-tracing/ md_url: https://wso2.com/api-platform/docs/api-gateway/observability/tracing/enabling-tracing.md @@ -12,17 +12,17 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# Enabling and Disabling Tracing +# Enabling and disabling tracing -## Enabling Tracing +## Enabling tracing -### Configuration Required +### Configuration required You need to enable tracing in the gateway configuration file and point it to your OTLP collector endpoint. The tracing configuration is located in `gateway/configs/config.toml`: -#### Policy Engine Tracing Configuration +#### Policy engine tracing configuration ```toml [tracing] @@ -34,13 +34,13 @@ max_export_batch_size = 512 # Maximum spans per batch sampling_rate = 1.0 # Sample rate (1.0 = 100%, 0.5 = 50%) ``` -### Demonstrated Tracing Services +### Demonstrated tracing services The tracing services included in the Docker Compose file (Jaeger and OpenTelemetry Collector) are provided as **demonstration services** to show one possible way to collect and visualize traces. You can use them as-is for development/testing, or replace them with your own tracing solution. The gateway uses Docker Compose profiles to optionally enable these demonstration tracing services. -### Start Gateway with Demonstrated Tracing Services +### Start gateway with demonstrated tracing services To start the gateway with the demonstration tracing services enabled: @@ -53,7 +53,7 @@ This starts: - OpenTelemetry Collector - *receives and processes traces* - Jaeger - *stores and visualizes traces* -### Start Gateway without Tracing Services +### Start gateway without tracing services To run only the core gateway services without the demonstration tracing stack: @@ -63,7 +63,7 @@ docker compose up -d **Note:** If tracing is enabled in the configuration but the OTLP collector is not running, components will log warnings about failed trace exports. To completely disable tracing, set `enabled = false` in the configuration. -### Stop Tracing Services +### Stop tracing services To stop all services including the tracing stack: @@ -73,7 +73,7 @@ docker compose --profile tracing down **Note:** Jaeger stores traces in memory by default. Stopping the service will lose all trace data. For persistent storage, configure Jaeger with a backend database (see Jaeger documentation). -## Disabling Tracing +## Disabling tracing To completely disable tracing: diff --git a/en/docs/api-gateway/observability/tracing/overview.md b/en/docs/api-gateway/observability/tracing/overview.md index 1688b581..bb53a1ac 100644 --- a/en/docs/api-gateway/observability/tracing/overview.md +++ b/en/docs/api-gateway/observability/tracing/overview.md @@ -1,5 +1,5 @@ --- -title: "Distributed Tracing Overview" +title: "Distributed tracing overview" description: "Overview of the distributed tracing architecture for API Platform Gateway: how components export traces through the OpenTelemetry Collector to Jaeger." canonical_url: https://wso2.com/api-platform/docs/api-gateway/observability/tracing/overview/ md_url: https://wso2.com/api-platform/docs/api-gateway/observability/tracing/overview.md @@ -12,7 +12,7 @@ last_updated: 2026-06-17 content_type: "concept" --- -# Gateway Tracing +# Gateway tracing This guide explains how to implement and configure distributed tracing for the API Platform Gateway components. @@ -22,14 +22,14 @@ The default tracing services included in the Docker Compose configuration are ** **Important**: You are free to choose any tracing or observability strategy that suits your environment and requirements. The provided setup is just one of many possible configurations. -## Tracing Architecture +## Tracing architecture The default tracing stack consists of: - **OpenTelemetry (OTLP) Collector**: Receives, processes, and exports trace data from gateway components - **Jaeger**: Stores and visualizes distributed traces with a web UI for trace exploration and analysis -### How It Works +### How it works 1. Gateway components (gateway-controller, policy-engine, router) are configured to export traces via OTLP (OpenTelemetry Protocol) 2. Components send trace spans to the OpenTelemetry Collector via gRPC (port 4317) or HTTP (port 4318) @@ -37,15 +37,15 @@ The default tracing stack consists of: 4. The OTLP Collector forwards traces to Jaeger for storage and visualization 5. Users can view and analyze traces through the Jaeger UI -### What is Distributed Tracing? +### What is distributed tracing? Distributed tracing tracks a request as it flows through multiple components, using a few key concepts: - **Trace**: Represents the entire journey of a request through the system - **Span**: Represents a single operation within a trace (e.g., policy execution, upstream call) -- **Context Propagation**: Traces are correlated across components using trace IDs and span IDs in headers +- **Context propagation**: Traces are correlated across components using trace IDs and span IDs in headers -## In This Section +## In this section - [Enabling and Disabling Tracing](enabling-tracing.md) — Turn tracing on or off and run the demonstration tracing services - [Viewing Traces in Jaeger](viewing-traces-in-jaeger.md) — Search, analyze, and compare distributed traces in the Jaeger UI @@ -53,7 +53,7 @@ Distributed tracing tracks a request as it flows through multiple components, us - [Alternative Tracing Backends](alternative-backends.md) — Export traces to Moesif, Zipkin, Tempo, and cloud-native solutions - [Best Practices and Troubleshooting](best-practices-and-troubleshooting.md) — Recommendations, common issues, and integration with logging -## Additional Resources +## Additional resources - [OpenTelemetry Documentation](https://opentelemetry.io/docs/) - [Jaeger Documentation](https://www.jaegertracing.io/docs/) diff --git a/en/docs/api-gateway/observability/tracing/viewing-traces-in-jaeger.md b/en/docs/api-gateway/observability/tracing/viewing-traces-in-jaeger.md index cc7cc2bd..4ff18c00 100644 --- a/en/docs/api-gateway/observability/tracing/viewing-traces-in-jaeger.md +++ b/en/docs/api-gateway/observability/tracing/viewing-traces-in-jaeger.md @@ -1,5 +1,5 @@ --- -title: "View Traces in Jaeger" +title: "View traces in Jaeger" description: "Access the Jaeger UI and search for distributed traces from API Platform Gateway components." canonical_url: https://wso2.com/api-platform/docs/api-gateway/observability/tracing/viewing-traces-in-jaeger/ md_url: https://wso2.com/api-platform/docs/api-gateway/observability/tracing/viewing-traces-in-jaeger.md @@ -13,7 +13,7 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# Viewing Traces in Jaeger +# Viewing traces in Jaeger Once you've started the gateway with the tracing profile, follow these steps to view distributed traces: @@ -24,7 +24,7 @@ Open your browser and navigate to: http://localhost:16686 ``` -## Step 2: Search for Traces +## Step 2: Search for traces The Jaeger UI provides several ways to search for traces: @@ -36,28 +36,28 @@ The Jaeger UI provides several ways to search for traces: - Choose "all" to see all operations - Or select a specific operation (e.g., specific policy execution) -3. **Adjust Lookback Time Range**: +3. **Adjust lookback time range**: - Default: Last 1 hour - Options: 5m, 15m, 1h, 6h, 12h, 1d, 2d, Custom -4. **Add Filters** (optional): +4. **Add filters** (optional): - **Tags**: Filter by specific tag values (e.g., `http.status_code=500`) - - **Min/Max Duration**: Filter by trace duration - - **Limit Results**: Control number of traces returned (default: 20) + - **Min/Max duration**: Filter by trace duration + - **Limit results**: Control number of traces returned (default: 20) 5. Click **Find Traces** -## Step 3: Analyze Trace Details +## Step 3: Analyze trace details Click on any trace in the results to view detailed information: -### Trace Timeline +### Trace timeline - **Visual timeline** showing all spans in the trace - **Duration bars** showing relative time spent in each operation - **Parent-child relationships** between spans - **Color coding** by service -### Span Details +### Span details Click on any span to see: - **Operation name**: What operation was performed - **Duration**: How long it took @@ -65,31 +65,31 @@ Click on any span to see: - **Logs**: Events logged during the span (errors, warnings, etc.) - **Process**: Service name, version, and host information -### Common Use Cases +### Common use cases -**Finding Slow Requests:** +**Finding slow requests:** 1. Set Min Duration filter (e.g., 1000ms) 2. Click Find Traces 3. Examine spans to identify bottlenecks -**Debugging Errors:** +**Debugging errors:** 1. Filter by tag: `error=true` or `http.status_code=500` 2. Click on error traces 3. Examine span logs and tags for error details -**Understanding Request Flow:** +**Understanding request flow:** 1. Search for a specific trace ID (from logs or headers) 2. View the complete request path through all components 3. Identify which component handled which part of the request -## Step 4: Trace Comparison +## Step 4: Trace comparison You can compare multiple traces to identify patterns: 1. Select multiple traces using checkboxes 2. Click **Compare Traces** button 3. View side-by-side comparison of trace structure and timings -## Step 5: Service Dependency Graph +## Step 5: Service dependency graph View how services interact: 1. Click **Dependencies** in the top navigation diff --git a/en/docs/api-gateway/overview.md b/en/docs/api-gateway/overview.md index d54b6d5c..d30d8cb8 100644 --- a/en/docs/api-gateway/overview.md +++ b/en/docs/api-gateway/overview.md @@ -1,5 +1,5 @@ --- -title: "API Platform Gateway Overview" +title: "API Platform gateway overview" description: "Learn the architecture and components of API Platform Gateway: Gateway Controller, Gateway Runtime, Policy Engine, default ports, and the ap CLI." canonical_url: https://wso2.com/api-platform/docs/api-gateway/overview/ md_url: https://wso2.com/api-platform/docs/api-gateway/overview.md @@ -12,7 +12,7 @@ last_updated: 2026-06-11 content_type: "concept" --- -# API Platform Gateway Overview +# API Platform gateway overview API Platform Gateway is the complete API gateway system for managing, securing, and routing API traffic to your backend services. @@ -21,10 +21,10 @@ API Platform Gateway is the complete API gateway system for managing, securing, | Component | Purpose | |-----------|---------| | **Gateway-Controller** | Control plane that manages API configurations and dynamically configures the Router | -| **Gateway-Runtime** | Data plane (Envoy Proxy) that routes HTTP/HTTPS traffic to backend services and Processes requests/responses through configurable policies (authentication, rate limiting, etc.)| +| **Gateway-Runtime** | Data plane (Envoy Proxy) that routes HTTP/HTTPS traffic to backend services and processes requests/responses through configurable policies (authentication, rate limiting, etc.)| | **Policy Builder** | Build-time tooling for compiling custom policy implementations | -### CLI Tool (ap) +### CLI tool (ap) The `ap` CLI provides a command-line interface for managing gateways, APIs, and MCP proxies. Key capabilities include: @@ -34,7 +34,7 @@ The `ap` CLI provides a command-line interface for managing gateways, APIs, and For the complete list of CLI commands and usage examples, see the [CLI Reference](../tools/cli/reference.md). -## Default Ports +## Default ports | Port | Service | Description | |------|---------|-------------| @@ -78,7 +78,7 @@ The complete and up-to-date policy catalogue — with configuration references a You can extend the gateway with your own policies or include specific policies from the catalogue by building a custom gateway image using the `ap` CLI. See [Building the Gateway with Custom Policies](./policies/custom-policies/building-gateway-with-custom-policies.md). -## High Availability Setup +## High availability setup In a production HA deployment: diff --git a/en/docs/api-gateway/policies/custom-policies/building-gateway-with-custom-policies.md b/en/docs/api-gateway/policies/custom-policies/building-gateway-with-custom-policies.md index 8f2a5ef2..bf8bd66b 100644 --- a/en/docs/api-gateway/policies/custom-policies/building-gateway-with-custom-policies.md +++ b/en/docs/api-gateway/policies/custom-policies/building-gateway-with-custom-policies.md @@ -1,5 +1,5 @@ --- -title: "Build a Gateway Image with Custom Policies" +title: "Build a gateway image with custom policies" description: "Use API Platform CLI to bundle custom policies into an API Platform Gateway Docker image for deployment." canonical_url: https://wso2.com/api-platform/docs/api-gateway/policies/custom-policies/building-gateway-with-custom-policies/ md_url: https://wso2.com/api-platform/docs/api-gateway/policies/custom-policies/building-gateway-with-custom-policies.md @@ -13,9 +13,9 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# Building the Gateway with Custom Policies +# Building the gateway with custom policies -## Install the AP CLI Tool +## Install the AP CLI tool The `ap` CLI tool is used to build a custom gateway image with your own policies. Download the binary for your platform from the [AP CLI releases page](https://github.com/wso2/api-platform/releases/tag/ap%2Fv0.7.0) and follow the steps below to install it. @@ -91,7 +91,7 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies ap --version ``` -## Configure the Build File +## Configure the build file The `build.yaml` file is already included in the unzipped gateway package. It declares the gateway version and the list of policies to include. Edit this file to add your custom policies before building the gateway image. @@ -118,7 +118,7 @@ Each policy entry uses one of two source types: | `gomodule` | Go module reference for policy hub managed policies (e.g., `github.com/wso2/gateway-controllers/policies/cors@v1`) | | `filePath` | Relative path from `build.yaml` to a local custom policy directory | -### Adding a Custom Policy +### Adding a custom policy Your custom policy can reside anywhere on the filesystem. Use a relative path from the `build.yaml` file to point to it. @@ -143,7 +143,7 @@ policies: !!! note The path in `filePath` is always relative to the location of `build.yaml`, not the directory from which you run the `ap` command. -## Build the Gateway Image +## Build the gateway image Once `build.yaml` is ready, run the following command from the directory containing `build.yaml` to build the custom gateway image: @@ -163,7 +163,7 @@ Once the build completes, the output lists the two image names produced. For exa A `build-manifest.yaml` file is also written alongside `build.yaml`, recording the resolved versions of all policies included in the build. -## Update the Docker Compose File +## Update the Docker compose file After building, update the `image:` fields in your `docker-compose.yaml` to use the newly built images. diff --git a/en/docs/api-gateway/policies/custom-policies/writing-a-custom-policy.md b/en/docs/api-gateway/policies/custom-policies/writing-a-custom-policy.md index 86b5543d..f76984e8 100644 --- a/en/docs/api-gateway/policies/custom-policies/writing-a-custom-policy.md +++ b/en/docs/api-gateway/policies/custom-policies/writing-a-custom-policy.md @@ -1,5 +1,5 @@ --- -title: "Write a Custom Gateway Policy" +title: "Write a custom gateway policy" description: "Write a custom policy for API Platform Gateway using the Go SDK: implement request and response hooks in the policy chain." canonical_url: https://wso2.com/api-platform/docs/api-gateway/policies/custom-policies/writing-a-custom-policy/ md_url: https://wso2.com/api-platform/docs/api-gateway/policies/custom-policies/writing-a-custom-policy.md @@ -12,13 +12,13 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# Writing a Custom Policy +# Writing a custom policy This guide shows how to write a custom policy in API Platform Gateway. For full API details, see the [API Platform Gateway's Custom Policy SDK Documentation](https://pkg.go.dev/github.com/wso2/api-platform/sdk/core/policy/v1alpha2). -## How It Works +## How it works Every request and response that flows through the gateway passes through a **policy chain**. Each policy in the chain declares which phases it participates in, and the kernel calls the appropriate hook for each phase: @@ -50,9 +50,9 @@ Incoming Request A policy only participates in the phases it implements. For example, a policy that only inspects request headers does not implement the response interfaces. -## How to Write a Policy +## How to write a policy -### Step 1: Create the Policy +### Step 1: Create the policy Each policy lives in its own Go module. Create a "policies" directory inside your gateway: @@ -63,7 +63,7 @@ Each policy lives in its own Go module. Create a "policies" directory inside you └── policy-definition.yaml ``` -### Step 2: Implement the Base Policy Interface +### Step 2: Implement the base policy interface ```go package mypolicy @@ -91,7 +91,7 @@ func (p *MyPolicy) Mode() policy.ProcessingMode { } ``` -#### How to Choose Modes +#### How to choose modes | Setting | When to Use | |---------|-------------| @@ -101,13 +101,13 @@ func (p *MyPolicy) Mode() policy.ProcessingMode { !!! tip If you do not want your policy to process a specific phase, explicitly set it to `Skip`. -### Step 3: Implement Phase Interfaces +### Step 3: Implement phase interfaces Implement only the interfaces for phases you declared in `Mode()` in step 2. -#### Request Flow +#### Request flow -**Request Header Phase** +**Request header phase** Called before the request body is read. Ideal for authentication, routing decisions, and adding/removing headers. @@ -128,7 +128,7 @@ func (p *MyPolicy) OnRequestHeaders( } ``` -**Request Body Phase** +**Request body phase** `OnRequestBody` is called only when the request body is fully buffered. @@ -148,9 +148,9 @@ func (p *MyPolicy) OnRequestBody( !!! note Even if your policy is designed for streaming, you must still implement `OnRequestBody`. This acts as a fallback when the policy chain does not run in streaming mode. -#### Response Flow +#### Response flow -**Response Header Phase** +**Response header phase** Called after the upstream responds but before the response body is read. @@ -168,7 +168,7 @@ func (p *MyPolicy) OnResponseHeaders( } ``` -**Response Body Phase** +**Response body phase** `OnResponseBody` is called only when the response body is fully buffered. @@ -191,11 +191,11 @@ func (p *MyPolicy) OnResponseBody( !!! note Even if your policy is designed for streaming, you must still implement `OnResponseBody`. This acts as a fallback when the policy chain does not run in streaming mode. -### Step 4: Enable Streaming +### Step 4: Enable streaming Use streaming when processing SSE (Server-Sent Events) responses or large chunked transfers where you cannot or should not buffer the full body. Set `ResponseBodyMode: policy.BodyModeStream` (and/or `RequestBodyMode: policy.BodyModeStream`) in your `Mode()`, then implement the streaming interfaces. -#### Streaming Request +#### Streaming request Implement `StreamingRequestPolicy` to process request chunks: @@ -233,7 +233,7 @@ func (p *MyPolicy) OnRequestBody( } ``` -#### Streaming Response +#### Streaming response Implement `StreamingResponsePolicy` to process responses chunk by chunk: @@ -285,7 +285,7 @@ func (p *MyPolicy) OnResponseBody( } ``` -#### Gate-then-Stream Pattern +#### Gate-then-stream pattern A common pattern for guardrail policies is to accumulate chunks until you have enough data to make a decision, then switch to pass-through: @@ -297,7 +297,7 @@ func (p *MyPolicy) NeedsMoreResponseData(accumulated []byte) bool { } ``` -### Step 5: Factory Function +### Step 5: Factory function Initialize your policy and validate parameters: @@ -316,7 +316,7 @@ func GetPolicy( } ``` -### Step 6: Define Parameters +### Step 6: Define parameters Create a `policy-definition.yaml` in your policy directory: @@ -333,7 +333,7 @@ parameters: default: 1048576 ``` -### Step 7: Share Data Between Phases +### Step 7: Share data between phases Use the `Metadata` map to pass data between request and response phases: @@ -345,7 +345,7 @@ reqCtx.Metadata["clientID"] = clientID clientID := respCtx.Metadata["clientID"] ``` -### Step 8: Register and Build +### Step 8: Register and build Add your policy to gateway folder's `build.yaml` under `policies:` using `filePath` for local development: @@ -363,6 +363,6 @@ policies: gomodule: github.com/abc/policy-repo/policies/my-policy@v1 ``` -## What's Next? +## What's next? - [Building the Gateway with Custom Policies](building-gateway-with-custom-policies.md): Build a gateway image that includes your custom policy diff --git a/en/docs/api-gateway/policies/overview.md b/en/docs/api-gateway/policies/overview.md index 8bb57d50..2e9f7186 100644 --- a/en/docs/api-gateway/policies/overview.md +++ b/en/docs/api-gateway/policies/overview.md @@ -1,5 +1,5 @@ --- -title: "API Platform Policies Overview" +title: "API Platform policies overview" description: "Understand gateway policies in WSO2 API Platform: how Go and Python policies execute in the request and response pipeline and how to chain them." canonical_url: https://wso2.com/api-platform/docs/api-gateway/policies/overview/ md_url: https://wso2.com/api-platform/docs/api-gateway/policies/overview.md @@ -12,9 +12,9 @@ last_updated: 2026-06-11 content_type: "concept" --- -# API Platform Policies Overview +# API Platform policies overview -## What is a Policy? +## What is a policy? A policy is a pluggable unit of behavior that runs in the gateway request or response pipeline. Policies can be applied at the API level (all operations) or at individual operation level, and can run on requests, responses, or both. @@ -24,7 +24,7 @@ Each built-in policy is versioned independently. When a new version is published You can also write your own policy and then use API Platform CLI to build a custom gateway image that includes any combination of built-in policies and your own implementations. For more information, see [Custom Policies](custom-policies/writing-a-custom-policy.md). -## Policy Languages and Runtimes +## Policy languages and runtimes The gateway supports **two languages** for authoring policies: @@ -35,7 +35,7 @@ The gateway supports **two languages** for authoring policies: Go is the **primary and recommended language** for policy development. It provides maximum execution performance, strict type safety, and minimal per-request latency. Python is available as a **specialized runtime** for use cases where access to Python-native libraries (NLP toolkits, compression engines, ML inference clients, etc.) outweighs the overhead of cross-process communication. -## How Policies Execute +## How policies execute Understanding where each language fits requires a brief look at the Gateway Runtime architecture: @@ -62,14 +62,14 @@ Understanding where each language fits requires a brief look at the Gateway Runt !!! note Both Go and Python policies share the same policy evaluation pipeline. From the perspective of API configuration and deployment, a policy's language is transparent — you attach Go and Python policies to APIs in exactly the same way. -## Policy Anatomy +## Policy anatomy Regardless of language, every policy consists of two parts: * Policy definition * Policy implementation -### Policy Definition (`policy-definition.yaml`) +### Policy definition (`policy-definition.yaml`) A declarative YAML file that describes the policy's identity, version, and configuration schema. This file is the same for both Go and Python policies. @@ -103,22 +103,22 @@ systemParameters: | `parameters` | JSON Schema describing the user-configurable parameters for the policy | | `systemParameters` | JSON Schema for operator-level configuration (set via gateway config, not per-API) | -### Policy Implementation +### Policy implementation The implementation is where the two languages diverge. -### Go Policies +### Go policies Go is the **default and recommended** language for policy development. Every built-in policy that ships with the gateway — authentication, rate limiting, CORS, guardrails, header manipulation — is written in Go. -#### Why Go? +#### Why go? - **Performance:** Compiled into the Policy Engine binary. No serialization, no IPC, no interpreter overhead. - **Type safety:** Compile-time guarantees reduce runtime errors in production. - **Ecosystem alignment:** The Policy Engine, Gateway Builder, and Gateway Controller are all Go codebases. - **Broad applicability:** Ideal for the vast majority of API management use cases. -#### Go Policy Structure +#### Go policy structure A Go policy is a standard **Go module** containing the policy definition and the implementation: @@ -140,7 +140,7 @@ my-go-policy/ Go policies implement interfaces from the gateway's Policy SDK. The Policy Engine loads them at build time via the `build.yaml` manifest. -#### Build Integration +#### Build integration Go policies are referenced in `build.yaml` using the `gomodule` field, which points to the Go module path: @@ -152,17 +152,17 @@ policies: The **Gateway Builder** resolves these modules, compiles them into the Policy Engine binary, and produces a custom gateway image containing all declared policies. -### Python Policies (Beta) +### Python policies (beta) Python policy support extends the gateway's capabilities into domains where Python's ecosystem is unmatched — particularly **AI/ML, natural language processing, and complex data transformations**. -#### Why Python? +#### Why python? - **AI/ML ecosystem:** Direct access to libraries like `transformers`, `tiktoken`, `scikit-learn`, and custom compression engines. - **Rapid prototyping:** Faster iteration for experimental or research-oriented policies. - **Specialized use cases:** Prompt compression, semantic analysis, content classification, and other tasks where Python libraries provide capabilities that would be impractical to reimplement in Go. -#### Python Policy Structure +#### Python policy structure Python policies follow the standard `src` layout and are packaged as installable Python packages: @@ -187,7 +187,7 @@ my-python-policy/ | `src//policy.py` | Policy implementation | | `tests/` | Unit tests for the policy logic | -#### Build Integration +#### Build integration Python policies are referenced in `build.yaml` using the `pipPackage` field instead of `gomodule`: @@ -199,7 +199,7 @@ policies: The Gateway Builder resolves the Python package, installs its dependencies, generates the policy registry, and bundles everything into the gateway image alongside the Python Executor. -## Choosing a Language for Policy +## Choosing a language for policy Use this decision guide when planning a new policy: @@ -215,7 +215,7 @@ Use this decision guide when planning a new policy: Start with Go unless your policy specifically requires Python libraries or Python-native capabilities. The majority of gateway policies are written in Go. -## Available Policies +## Available policies The following table presents the available policies alphabetically. diff --git a/en/docs/api-gateway/quick-start-guide.md b/en/docs/api-gateway/quick-start-guide.md index 1b236aa1..88970517 100644 --- a/en/docs/api-gateway/quick-start-guide.md +++ b/en/docs/api-gateway/quick-start-guide.md @@ -1,5 +1,5 @@ --- -title: "API Platform Gateway Quick Start Guide" +title: "API Platform gateway quick start guide" description: "Run API Platform Gateway with Docker Compose, deploy your first REST API configuration, and invoke it through the gateway in minutes." canonical_url: https://wso2.com/api-platform/docs/api-gateway/quick-start-guide/ md_url: https://wso2.com/api-platform/docs/api-gateway/quick-start-guide.md @@ -12,9 +12,9 @@ last_updated: 2026-06-11 content_type: "quickstart" --- -# Quick Start Guide +# Quick start guide -### Using Docker Compose (Recommended) +### Using Docker compose (recommended) ### Prerequisites @@ -96,17 +96,17 @@ curl -i http://localhost:8080/reading-list/v1.0/books curl -ik https://localhost:8443/reading-list/v1.0/books ``` -### Stopping the Gateway +### Stopping the gateway When stopping the gateway, you have two options: -**Option 1: Stop runtime, keep data (persisted APIs and configuration)** +**Option 1: stop runtime, keep data (persisted APIs and configuration)** ```bash docker compose down ``` This stops the containers but preserves the `controller-data` volume. When you restart with `docker compose up`, all your API configurations will be restored. -**Option 2: Complete shutdown with data cleanup (fresh start)** +**Option 2: complete shutdown with data cleanup (fresh start)** ```bash docker compose down -v ``` diff --git a/en/docs/api-gateway/setup/artifact-templating.md b/en/docs/api-gateway/setup/artifact-templating.md index 3cb89160..51ed0364 100644 --- a/en/docs/api-gateway/setup/artifact-templating.md +++ b/en/docs/api-gateway/setup/artifact-templating.md @@ -1,5 +1,5 @@ --- -title: "Artifact Templating" +title: "Artifact templating" description: "Use Go text template expressions in API Platform Gateway YAML artifacts to inject environment variables and dynamic values at startup." canonical_url: https://wso2.com/api-platform/docs/api-gateway/setup/artifact-templating/ md_url: https://wso2.com/api-platform/docs/api-gateway/setup/artifact-templating.md @@ -12,7 +12,7 @@ last_updated: 2026-06-17 content_type: "reference" --- -# Gateway Artifact Templating +# Gateway artifact templating Gateway artifact files (YAML/JSON) support Go `text/template` expressions for injecting dynamic values at startup. Templates are rendered on the raw artifact string before YAML/JSON parsing, so expressions work in any string field across the entire artifact — `upstream`, `auth`, policy `params`, metadata, etc. diff --git a/en/docs/api-gateway/setup/storage-and-backends.md b/en/docs/api-gateway/setup/storage-and-backends.md index 83c411b9..70636dcb 100644 --- a/en/docs/api-gateway/setup/storage-and-backends.md +++ b/en/docs/api-gateway/setup/storage-and-backends.md @@ -1,5 +1,5 @@ --- -title: "Configuring External Storage and Backends" +title: "Configuring external storage and backends" description: "Configure PostgreSQL as the Gateway Controller storage backend and Redis for distributed rate limiting in API Platform Gateway." canonical_url: https://wso2.com/api-platform/docs/api-gateway/setup/storage-and-backends/ md_url: https://wso2.com/api-platform/docs/api-gateway/setup/storage-and-backends.md @@ -12,9 +12,9 @@ last_updated: 2026-06-11 content_type: "how-to" --- -# Configuring External Storage and Backends +# Configuring external storage and backends -### PostgreSQL (Gateway Controller) +### PostgreSQL (gateway controller) To use PostgreSQL as the storage backend for the Gateway Controller, update the `config.toml`: @@ -32,7 +32,7 @@ password = "your-postgres-password" For the full list of PostgreSQL configuration options, refer to the [config template](https://github.com/wso2/api-platform/blob/main/gateway/configs/config-template.toml). -### Redis (Gateway Runtime — Distributed Rate Limiting) +### Redis (gateway runtime — distributed rate limiting) To enable distributed rate limiting across multiple Gateway Runtime instances, configure the rate limiting policy to use Redis as the backend in `config.toml`: diff --git a/en/docs/api-gateway/setup/upstream-timeouts.md b/en/docs/api-gateway/setup/upstream-timeouts.md index e0e9820a..7ffd45c0 100644 --- a/en/docs/api-gateway/setup/upstream-timeouts.md +++ b/en/docs/api-gateway/setup/upstream-timeouts.md @@ -1,5 +1,5 @@ --- -title: "Configure Upstream Timeouts" +title: "Configure upstream timeouts" description: "Configure the upstream TCP connection timeout in API Platform Gateway to protect against slow or unreachable backend services." canonical_url: https://wso2.com/api-platform/docs/api-gateway/setup/upstream-timeouts/ md_url: https://wso2.com/api-platform/docs/api-gateway/setup/upstream-timeouts.md @@ -12,7 +12,7 @@ last_updated: 2026-06-17 content_type: "how-to" --- -# Gateway Upstream Timeouts +# Gateway upstream timeouts This guide explains how to configure **upstream connect timeouts** for the API Platform Gateway router so that requests to slow or unreachable backends fail within a predictable time instead of hanging indefinitely. diff --git a/en/docs/api-manager/overview.md b/en/docs/api-manager/overview.md index 5061c308..16967e26 100644 --- a/en/docs/api-manager/overview.md +++ b/en/docs/api-manager/overview.md @@ -1,5 +1,5 @@ --- -title: "WSO2 API Manager Overview" +title: "WSO2 API Manager overview" description: "A high-level map of WSO2 API Manager's capabilities for designing, governing, and monetizing APIs across cloud, on-premise, and hybrid architectures." canonical_url: https://wso2.com/api-platform/docs/api-manager/overview/ md_url: https://wso2.com/api-platform/docs/api-manager/overview.md @@ -12,7 +12,7 @@ last_updated: 2026-06-11 content_type: "concept" --- -# WSO2 API Manager Overview +# WSO2 API Manager overview WSO2 API Manager is a complete platform for building, integrating, and exposing your digital services as managed APIs. Irrespective of cloud, on-premise, or hybrid architectures, API Manager provides the tools to drive your digital transformation strategy from design to deployment. @@ -20,11 +20,11 @@ Visit [the API Manager documentation website](https://apim.docs.wso2.com/en/late This page provides a high-level map of the API Manager's capabilities to help you understand the ecosystem. -## Core Capabilities +## Core capabilities The platform is divided into several key functional areas to manage the entire API lifecycle: -### Design and Manage APIs +### Design and manage APIs Build, iterate, and apply policies to your APIs and API products. * **API Design Toolkit:** Create, document, and mock REST, GraphQL, and AsyncAPI specifications. @@ -51,5 +51,5 @@ Oversee the security, usage, and automation of your API ecosystem. ### Administration Configure and manage the core system, users, and tenants. Manage system-wide policies (like rate limiting), register external Gateways and Key Managers, and oversee global configurations. -## What's Next? +## What's next? Follow [the 15-minute quick start guide](https://apim.docs.wso2.com/en/4.7.0/get-started/api-manager-quick-start-guide/) to get started with API Manager. diff --git a/en/docs/cloud/administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp.md b/en/docs/cloud/administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp.md index 1822b94b..2b6c071a 100644 --- a/en/docs/cloud/administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp.md +++ b/en/docs/cloud/administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp.md @@ -1,4 +1,4 @@ -# Configure Asgardeo as an External Key Manager +# Configure Asgardeo as an external key manager Asgardeo is an identity-as-a-service (IDaaS) solution designed to create seamless login experiences for your applications. Asgardeo seamlessly integrates with API Platform, providing powerful API access control through the use of API scopes. This enables restricting API access to designated user groups. By configuring Asgardeo as an external key manager in API Platform, you can leverage your Asgardeo user stores to manage API access control effectively. This guide walks you through the steps to set up Asgardeo as your external key manager. @@ -63,6 +63,6 @@ Now you have configured Asgardeo as an external key manager in API Platform Deve ![Developer Portal Key Managers tab with external-asgardeo-km selected and Save button](../../../assets/img/administer/settings/external-km/add_external_km_asgardeo_devportal.png) -## What Next? +## What next? To secure API access with the above-configured Asgardeo as key manager, follow the steps mentioned [here](../../develop-api-proxy/authentication-and-authorization/secure-api-access-with-asgardeo.md). diff --git a/en/docs/cloud/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md b/en/docs/cloud/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md index b55f46c0..1eb37877 100644 --- a/en/docs/cloud/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md +++ b/en/docs/cloud/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md @@ -1,4 +1,4 @@ -# Configure Azure Active Directory (Azure AD) as an External Key Manager +# Configure Azure Active Directory (Azure AD) as an external key manager In organizations leveraging Microsoft Azure Active Directory (Azure AD) as a key manager, integrating it with API Platform offers powerful API access control. This control hinges on the use of API scopes. That is, it enables the restriction of access to a designated group of users. This document guide you step-by-step to configure Azure AD as your external key manager. @@ -29,7 +29,7 @@ Follow the steps below to add Azure AD as a key manager in API Platform: 8. To obtain the `Well-Known URL` of your Azure AD instance, on your Azure account, under **Azure Active Directory** go to **App registrations**, and then **Endpoints**. Copy the URI under`OpenID Connect metadata document`. !!! info - - In azure, there are two versions of access tokens available. By default, the key manager applications you create use the v1 access token. Therefore, if you intend to use the v1 access token, when providing the `Well-Known URL`, omit the v2.0 path segment from the URL. [Learn more](https://learn.microsoft.com/en-us/azure/active-directory/develop/access-tokens#token-formats) + - In Azure, there are two versions of access tokens available. By default, the key manager applications you create use the v1 access token. Therefore, if you intend to use the v1 access token, when providing the `Well-Known URL`, omit the v2.0 path segment from the URL. [Learn more](https://learn.microsoft.com/en-us/azure/active-directory/develop/access-tokens#token-formats) For example, convert `https://login.microsoftonline.com//v2.0/.well-known/openid-configuration`-> `https://login.microsoftonline.com//.well-known/openid-configuration` - If you intend to work with v2.0, then the key manager application's manifest should be changed as explained in the [access token documentation](https://learn.microsoft.com/en-us/azure/active-directory/develop/access-tokens#token-formats). diff --git a/en/docs/cloud/administer/configure-an-external-idp/configure-custom-external-idp.md b/en/docs/cloud/administer/configure-an-external-idp/configure-custom-external-idp.md index d457697c..fb2c7008 100644 --- a/en/docs/cloud/administer/configure-an-external-idp/configure-custom-external-idp.md +++ b/en/docs/cloud/administer/configure-an-external-idp/configure-custom-external-idp.md @@ -1,4 +1,4 @@ -# Configure Custom External Key Manager +# Configure custom external key manager If your organization uses Asgardeo or Microsoft Azure Active Directory (Azure AD) as a key manager follow the platform-specific guides below to add them as an external key manager in API Platform. @@ -56,6 +56,6 @@ Now you have configured your key manager as an external key manager in API Platf ![Developer Portal Key Managers tab with custom-key-manager selected and Save button](../../../assets/img/administer/settings/external-km/add_external_km_custom_devportal.png) -## What Next? +## What next? To secure API access with the above-configured key manager follow the steps mentioned [here](../../develop-api-proxy/authentication-and-authorization/secure-api-access-with-external-idp.md). diff --git a/en/docs/cloud/administer/configure-enterprise-login/configure-enterprise-login.md b/en/docs/cloud/administer/configure-enterprise-login/configure-enterprise-login.md index d034722e..4c6a6a47 100644 --- a/en/docs/cloud/administer/configure-enterprise-login/configure-enterprise-login.md +++ b/en/docs/cloud/administer/configure-enterprise-login/configure-enterprise-login.md @@ -1,4 +1,4 @@ -# Configure Enterprise Login +# Configure enterprise login With API Platform, you can configure enterprise login to allow users from an external identity provider (IdP) to sign in to API Platform seamlessly without changing their credentials. @@ -111,7 +111,7 @@ Before you proceed with the configuration, make sure you complete the following: 3. Click **New Attribute** and select the **Groups** attribute. 4. Click **Save** and then click **Save Changes**. -### Step 2: Map API Platform groups to enterprise IdP groups via the API Platform Console +### Step 2: Map API Platform groups to enterprise idp groups via the API Platform console !!! note diff --git a/en/docs/cloud/administer/configure-vpns/configure-vpns.md b/en/docs/cloud/administer/configure-vpns/configure-vpns.md index daba1445..744543a7 100644 --- a/en/docs/cloud/administer/configure-vpns/configure-vpns.md +++ b/en/docs/cloud/administer/configure-vpns/configure-vpns.md @@ -1,4 +1,4 @@ -# Configure VPNs on the API Platform Cloud Data Plane +# Configure VPNs on the API Platform Cloud data plane Secure access to private networks from the API Platform cloud data plane is an essential use case for cloud data plane users. @@ -30,7 +30,7 @@ Let's take a look at the specifics of each part to understand the deployment arc Forwards inbound TCP (transmission control protocol) traffic from the Tailscale proxy container’s network interface to the SOCKS5 proxy, ensuring it reaches its destination via the secured WireGuard tunnel. -- **API Proxies and API Platform API gateway** +- **API proxies and API Platform API Gateway** API proxies within the same project as the Tailscale proxy can send their traffic to the ports exposed on the Tailscale proxy. The Tailscale proxy then forwards this traffic to the correct target node and IP address in your Tailscale network that is defined in the port mapping of the endpoint configuration @@ -82,9 +82,9 @@ Follow the steps given below: To configure and deploy the tailscale proxy, follow the steps given below: - 1. Enter Your Tailscale Auth Key + 1. Enter your Tailscale Auth key - To connect your system to Tailscale, you need an **Auth Key**. Follow the steps below to generate one: + To connect your system to Tailscale, you need an **Auth key**. Follow the steps below to generate one: - Visit the Tailscale Admin Keys page: [https://login.tailscale.com/admin/settings/keys](https://login.tailscale.com/admin/settings/keys) - Click on the **Generate Auth Key** button to create a new key. @@ -104,10 +104,10 @@ To configure and deploy the tailscale proxy, follow the steps given below: ii. In the "Add Endpoint Configuration" section of the Tailscale proxy interface, fill in the following fields: - - **Endpoint Name:** A descriptive name for the endpoint (e.g., `Internal Security APIs`). + - **Endpoint name:** A descriptive name for the endpoint (e.g., `Internal Security APIs`). - **Port:** The port on the Tailscale proxy that will receive incoming API traffic (e.g., `8090`). - **Target IP:** The IP address of the external device where the traffic should be forwarded (e.g., `192.168.1.1`). - - **Target Port:** The port on the external device that should receive the traffic (e.g., `9000`). + - **Target port:** The port on the external device that should receive the traffic (e.g., `9000`). iii. Click the **Add** button to save the endpoint and the port mapping. @@ -131,7 +131,7 @@ To configure and deploy the tailscale proxy, follow the steps given below: !!! note You can configure multiple endpoints and port mappings on the same Tailscale device, and also across multiple Tailscale devices. This allows you to forward traffic from different ports to different external devices as needed. -### Step 3: Configure API Proxy to forward traffic to Tailscale proxy +### Step 3: Configure API proxy to forward traffic to Tailscale proxy After the deployment is complete, the Tailscale proxy URL will be displayed in the environment view. diff --git a/en/docs/cloud/administer/manage-cd-pipelines/manage-cd-pipelines.md b/en/docs/cloud/administer/manage-cd-pipelines/manage-cd-pipelines.md index 8e61186d..2d6f3c1f 100644 --- a/en/docs/cloud/administer/manage-cd-pipelines/manage-cd-pipelines.md +++ b/en/docs/cloud/administer/manage-cd-pipelines/manage-cd-pipelines.md @@ -1,4 +1,4 @@ -# Manage Continuous Deployment Pipelines +# Manage continuous deployment pipelines By default, all the organizations in API Platform are provisioned with a default continuous deployment pipeline. diff --git a/en/docs/cloud/administer/manage-environments/manage-environments.md b/en/docs/cloud/administer/manage-environments/manage-environments.md index 3977fabb..94d6f0a5 100644 --- a/en/docs/cloud/administer/manage-environments/manage-environments.md +++ b/en/docs/cloud/administer/manage-environments/manage-environments.md @@ -1,4 +1,4 @@ -# Manage Environments +# Manage environments By default, all projects created in the cloud data planes (irrespective of the data plane region) are provisioned with two environments (i.e., development and production). @@ -14,13 +14,13 @@ To create a new environment, follow the steps given below: 4. On the **Environments** page, click **Create** and specify the following details to create a new environment: - **Name**: A display name for the new environment. - - **Data Plane** - The data plane to create the new environment. + - **Data plane** - The data plane to create the new environment. !!!tip - The **Data Plane** list displays all the private data planes registered under your organization. + The **Data plane** list displays all the private data planes registered under your organization. - - **DNS Prefix**: A DNS prefix to identify the exposed APIs in the environment. Here, the base domain depends on the custom domain attached to the API gateways provisioned on the selected data plane. - - **Mark environment as a Production environment**: Select if you want this environment to be a production environment. + - **DNS prefix**: A DNS prefix to identify the exposed APIs in the environment. Here, the base domain depends on the custom domain attached to the API gateways provisioned on the selected data plane. + - **Mark environment as a production environment**: Select if you want this environment to be a production environment. ![Create Environment form with Name, Data Plane, DNS Prefix fields, generated DNS URL preview, and Mark as Production checkbox](../../../assets/img/administer/settings/add-environment.png) diff --git a/en/docs/cloud/administer/settings/configure-a-custom-domain-for-your-organization.md b/en/docs/cloud/administer/settings/configure-a-custom-domain-for-your-organization.md index e5c98761..24077617 100644 --- a/en/docs/cloud/administer/settings/configure-a-custom-domain-for-your-organization.md +++ b/en/docs/cloud/administer/settings/configure-a-custom-domain-for-your-organization.md @@ -1,4 +1,4 @@ -# Configure a Custom Domain for Your Organization +# Configure a custom domain for your organization A custom domain is essential for effective branding, discoverability, and credibility of a website. API Platform allows you to easily configure custom domains for your organization, enabling developers to utilize it to configure custom URLs for their API proxies. @@ -22,7 +22,7 @@ To add a custom domain for your organization, follow the steps given below: 3. In the left navigation menu, under **Admin**, click **Settings**. This opens the organization-level settings page. 4. Click the **URL Settings** tab and then click the **Active Domains** tab. 5. Click **+ Add Domains**. -6. In the **Add a Custom Domain** pane, do the following: +6. In the **Add a custom domain** pane, do the following: 1. Enter your domain name. 2. Select the environment to apply the domain name. diff --git a/en/docs/cloud/administer/settings/create-api-subscription-plans.md b/en/docs/cloud/administer/settings/create-api-subscription-plans.md index 4bfbca4a..4d4e2da1 100644 --- a/en/docs/cloud/administer/settings/create-api-subscription-plans.md +++ b/en/docs/cloud/administer/settings/create-api-subscription-plans.md @@ -1,4 +1,4 @@ -# Create API Subscription Plans +# Create API subscription plans API subscription plans are essential to control and manage access to APIs. These plans define the rules and limitations on how clients can interact with APIs, ensuring efficient resource utilization and robust security. With the option to set rate limits, burst control, and pricing models, subscription plans allow API providers to manage traffic, prevent misuse, offer tiered service levels, and monetize APIs. Organizations can implement subscription plans to provide varying levels of API access, accommodating different user needs and business models, while ensuring optimal performance and security. diff --git a/en/docs/cloud/ai-gateway/analytics/analytics-header-filter.md b/en/docs/cloud/ai-gateway/analytics/analytics-header-filter.md index 3da00908..e81badba 100644 --- a/en/docs/cloud/ai-gateway/analytics/analytics-header-filter.md +++ b/en/docs/cloud/ai-gateway/analytics/analytics-header-filter.md @@ -1,4 +1,4 @@ -# Analytics Header Filter +# Analytics header filter ## Overview @@ -31,7 +31,7 @@ Request and response headers can have different operation modes, allowing for fl | `requestHeadersToFilter` | object | No | - | Configuration for filtering request headers. Contains `operation` and `headers` properties. | | `responseHeadersToFilter` | object | No | - | Configuration for filtering response headers. Contains `operation` and `headers` properties. | -### Parameter Structure +### Parameter structure Each filter parameter (`requestHeadersToFilter` and `responseHeadersToFilter`) is an object with the following properties: @@ -43,14 +43,14 @@ Each filter parameter (`requestHeadersToFilter` and `responseHeadersToFilter`) i > **Note**: This policy only affects analytics data collection. It does not remove or modify headers sent to upstream services or returned to clients. -## System Requirements +## System requirements * Analytics must be enabled globally via `config.yaml` (`analytics.enabled: true`) * The policy must be explicitly applied to the API policy chain * If analytics is disabled at the system level, this policy has no effect -## API Definition Example +## API definition example The following example demonstrates how to apply the Analytics Header Filter policy to a LlmProvider: @@ -98,7 +98,7 @@ spec: EOF ``` -## Use Cases +## Use cases - **Sensitive Data Protection**: Prevent authentication tokens, internal identifiers, or security-related headers from being sent to analytics systems. diff --git a/en/docs/cloud/ai-gateway/analytics/index.md b/en/docs/cloud/ai-gateway/analytics/index.md index 23f16a9c..f6ec1846 100644 --- a/en/docs/cloud/ai-gateway/analytics/index.md +++ b/en/docs/cloud/ai-gateway/analytics/index.md @@ -2,7 +2,7 @@ The AI Gateway analytics docs explain how to publish request and response metadata to external analytics systems. -## In This Section +## In this section - [Moesif Analytics](moesif-analytics.md) for platform-level analytics collection and publishing - [Analytics Header Filter](analytics-header-filter.md) for filtering analytics data before export diff --git a/en/docs/cloud/ai-gateway/analytics/moesif-analytics.md b/en/docs/cloud/ai-gateway/analytics/moesif-analytics.md index b47b51b4..2b262eb9 100644 --- a/en/docs/cloud/ai-gateway/analytics/moesif-analytics.md +++ b/en/docs/cloud/ai-gateway/analytics/moesif-analytics.md @@ -22,8 +22,8 @@ This capability allows platform administrators and business stakeholders to gain - Active Moesif Account and an Application ID > **Note:** For obtaining the Application ID: > - Step 1: Sign up in [Moesif](https://www.moesif.com/) -> - Sept 2: Follow the onboarding wizard. -> - Sept 3: During the sign up process, you will receive a Collector Application ID for your configured application. Copy this value and keep it saved. +> - Step 2: Follow the onboarding wizard. +> - Step 3: During the sign up process, you will receive a Collector Application ID for your configured application. Copy this value and keep it saved. > For more detailed instructions and advanced configuration options, refer to the [official Moesif Documentation](https://www.moesif.com/docs). @@ -32,7 +32,7 @@ This capability allows platform administrators and business stakeholders to gain Analytics is configured entirely through the gateway `config.toml` file and is enabled at a system level. -### System Parameters (`config.toml`) +### System parameters (`config.toml`) #### Analytics @@ -48,7 +48,7 @@ Analytics is configured entirely through the gateway `config.toml` file and is e | `enabled` | boolean | Yes | Enables the publisher | | `settings` | object | Yes | Map of Publisher specific attributes required for configuring the publisher client | -#### gRPC Event Server +#### gRPC event server This section configures both the Envoy access log streaming settings and the ALS (Access Log Service) server that receives those logs. The ALS server runs within the policy-engine component. @@ -68,9 +68,9 @@ This section configures both the Envoy access log streaming settings and the ALS **Note:** The hostname for the ALS connection is automatically derived from the policy-engine configuration. The internal log name identifier is set to `"envoy_access_log"` and is not configurable. -## Configuration Examples +## Configuration examples -#### Integrate Moesif Publisher +#### Integrate Moesif publisher For Moesif analytics integration, the following publisher-specific attributes must be configured under the `settings` section. These parameters control authentication, batching behavior, and publish intervals for efficient analytics delivery. The required attributes are as follows. @@ -110,7 +110,7 @@ max_header_limit = 8192 ``` -## Use Cases +## Use cases * **API Usage Visibility** – Understand how APIs are consumed across tenants and applications. * **Operational Insights** – Observe traffic volume, response behavior, and latency trends. diff --git a/en/docs/cloud/ai-gateway/gateway-controller-api.md b/en/docs/cloud/ai-gateway/gateway-controller-api.md index 7920201e..386fad06 100644 --- a/en/docs/cloud/ai-gateway/gateway-controller-api.md +++ b/en/docs/cloud/ai-gateway/gateway-controller-api.md @@ -1,21 +1,21 @@ -# Gateway-Controller API +# Gateway-controller API The Gateway-Controller API is the standalone management API exposed by AI Gateway on port `9090`. Administrators use it to create and manage LLM providers, LLM proxies, MCP proxies, and related runtime configuration when operating the gateway without AI Workspace. -## What You Can Manage +## What you can manage - LLM provider definitions and provider templates - Application-facing LLM proxies - MCP proxies and MCP traffic policies - Runtime configuration used by standalone AI Gateway deployments -## Where To Start +## Where to start - Use the [LLM Quick Start Guide](llm/quick-start-guide.md) to deploy the gateway and create LLM providers and proxies with the API - Use the [MCP Quick Start Guide](mcp/quick-start-guide.md) to deploy the gateway and create MCP proxies with the API - Use [LLM Provider Templates](llm/llm-templates.md) for provider template API examples -## Default Endpoint +## Default endpoint The Gateway-Controller API is exposed on: diff --git a/en/docs/cloud/ai-gateway/llm/ai-tools/claude-code-configuration-with-ai-gateway.md b/en/docs/cloud/ai-gateway/llm/ai-tools/claude-code-configuration-with-ai-gateway.md index 85e379ae..025280ff 100644 --- a/en/docs/cloud/ai-gateway/llm/ai-tools/claude-code-configuration-with-ai-gateway.md +++ b/en/docs/cloud/ai-gateway/llm/ai-tools/claude-code-configuration-with-ai-gateway.md @@ -49,13 +49,13 @@ Once the AI Gateway is active, you can continue to create the Anthropic LLM prov --- -## Step 2: Create and Deploy an Anthropic LLM Provider +## Step 2: Create and deploy an Anthropic LLM provider 1. **Log in to the WSO2 API Platform Console** as an admin. 2. Click **AI Workspace** at the top of the page. -### Create an Anthropic LLM Provider +### Create an Anthropic LLM provider 1. In the left navigation panel of the AI Workspace Console, navigate to **LLM → LLM Providers**. @@ -69,7 +69,7 @@ Once the AI Gateway is active, you can continue to create the Anthropic LLM prov 6. Click **Add Provider**. -### Deploy the Anthropic Provider to the AI Gateway +### Deploy the Anthropic provider to the AI Gateway 1. On the page that opens after creating the provider, click **Deploy to Gateway**. @@ -81,7 +81,7 @@ The Anthropic LLM provider is now deployed to the selected AI Gateway. --- -## Step 3: Create and Deploy an App LLM Proxy +## Step 3: Create and deploy an app LLM proxy The App LLM Proxy is the endpoint that Claude Code invokes through WSO2 API Platform. @@ -115,7 +115,7 @@ The App LLM Proxy is the endpoint that Claude Code invokes through WSO2 API Plat 12. Click **Create Proxy**. -### Deploy the App LLM Proxy to the AI Gateway +### Deploy the app LLM proxy to the AI Gateway 1. Click **Deploy to Gateway**. @@ -125,7 +125,7 @@ The App LLM Proxy is the endpoint that Claude Code invokes through WSO2 API Plat The App LLM Proxy is now deployed to the selected AI Gateway. -### Generate an API Key for Claude Code +### Generate an API key for Claude Code Claude Code needs an API key from WSO2 API Platform to invoke the deployed App LLM Proxy. @@ -147,11 +147,11 @@ You will use these values when configuring Claude Code. --- -## Step 4: Configure Claude Code to Use the App LLM Proxy +## Step 4: Configure Claude Code to use the app LLM proxy Claude Code can be configured using environment variables or through Claude Code's `settings.json` file. -### Configure Environment Variables +### Configure environment variables Open a terminal session where you want to run Claude Code. @@ -171,7 +171,7 @@ Replace: !!! note These environment variables apply only to the current terminal session. If you open a new terminal session, you must export them again. -!!! note "Persistent Configuration" +!!! note "Persistent configuration" To make the configuration permanent, add the environment variables to Claude Code's `settings.json` file. @@ -190,7 +190,7 @@ Replace: For more information, see [Claude Code's official documentation](https://code.claude.com/docs/en/settings). -### Configure SSL Certificate Trust +### Configure SSL certificate trust When using a local WSO2 API Platform AI Gateway over HTTPS, Claude Code must be able to trust the certificate presented by the Gateway. @@ -223,7 +223,7 @@ Claude Code will now send requests through WSO2 API Platform instead of directly ## Use case examples -### View API Analytics and Insights +### View API analytics and insights By routing Claude Code requests through the WSO2 API Manager AI Gateway, you automatically gain access to built-in analytics and reporting capabilities. @@ -237,7 +237,7 @@ For more information on Analytics, refer to the official [WSO2 API Platform Docu --- -### Implement WSO2 AI Gateway Guardrails for Enhanced Control +### Implement WSO2 AI Gateway guardrails for enhanced control WSO2 API Manager AI Gateway guardrails enable granular control over the data exchanged between Claude Code and the Anthropic API. @@ -269,7 +269,7 @@ For more information on Rate Limiting and other policies, refer to the official --- -### Prompt Decorator +### Prompt decorator WSO2 API Manager AI Gateway supports Prompt Decorators, which allow you to modify or enrich prompts before they are sent to the backend AI provider. This is useful for enforcing consistent instructions, adding system-level context, or guiding model behavior without requiring changes in the client application. diff --git a/en/docs/cloud/ai-gateway/llm/ai-tools/codex-configuration-with-ai-gateway.md b/en/docs/cloud/ai-gateway/llm/ai-tools/codex-configuration-with-ai-gateway.md index f73a217d..9487f072 100644 --- a/en/docs/cloud/ai-gateway/llm/ai-tools/codex-configuration-with-ai-gateway.md +++ b/en/docs/cloud/ai-gateway/llm/ai-tools/codex-configuration-with-ai-gateway.md @@ -49,13 +49,13 @@ Once the AI Gateway is active, you can continue to create the OpenAI LLM provide --- -## Step 2: Create and Deploy an OpenAI LLM Provider +## Step 2: Create and deploy an OpenAI LLM provider 1. **Log in to the WSO2 API Platform Console** as an admin. 2. Click **AI Workspace** at the top of the page. -### Create an OpenAI LLM Provider +### Create an OpenAI LLM provider 1. In the left navigation panel of the AI Workspace Console, navigate to **LLM → LLM Providers**. @@ -69,7 +69,7 @@ Once the AI Gateway is active, you can continue to create the OpenAI LLM provide 6. Click **Add Provider**. -### Deploy the OpenAI Provider to the AI Gateway +### Deploy the OpenAI provider to the AI Gateway 1. On the page that opens after creating the provider, click **Deploy to Gateway**. @@ -81,7 +81,7 @@ The OpenAI LLM provider is now deployed to the selected AI Gateway. --- -## Step 3: Create and Deploy an App LLM Proxy +## Step 3: Create and deploy an app LLM proxy The App LLM Proxy is the endpoint that Codex CLI invokes through WSO2 API Platform. @@ -115,7 +115,7 @@ The App LLM Proxy is the endpoint that Codex CLI invokes through WSO2 API Platfo 12. Click **Create Proxy**. -### Deploy the App LLM Proxy to the AI Gateway +### Deploy the app LLM proxy to the AI Gateway 1. Click **Deploy to Gateway**. @@ -125,7 +125,7 @@ The App LLM Proxy is the endpoint that Codex CLI invokes through WSO2 API Platfo The App LLM Proxy is now deployed to the selected AI Gateway. -### Generate an API Key for Codex CLI +### Generate an API key for Codex CLI Codex CLI needs an API key from WSO2 API Platform to invoke the deployed App LLM Proxy. @@ -147,7 +147,7 @@ You will use these values when configuring Codex CLI. --- -## Step 4: Configure Codex CLI to Use the App LLM Proxy +## Step 4: Configure Codex CLI to use the app LLM proxy Codex CLI can be configured to use a custom OpenAI-compatible provider by updating its `config.toml` file. @@ -181,7 +181,7 @@ Codex CLI can be configured to use a custom OpenAI-compatible provider by updati The configuration above instructs Codex CLI to use the WSO2 API Platform App LLM Proxy endpoint and send the WSO2 API Platform API key using the `X-API-Key` header. -### Configure Environment Variables for Codex CLI +### Configure environment variables for Codex CLI 1. Open a terminal session where you want to run Codex CLI. @@ -198,7 +198,7 @@ Codex CLI can be configured to use a custom OpenAI-compatible provider by updati --- -## Step 5: Configure the Gateway Certificate for Codex CLI +## Step 5: Configure the gateway certificate for Codex CLI When using a local WSO2 API Platform AI Gateway over HTTPS, Codex CLI must be able to trust the certificate presented by the Gateway. @@ -230,7 +230,7 @@ export SSL_CERT_FILE="/gateway_certificate.pem" --- -## Step 6: Run the Codex CLI Client +## Step 6: Run the Codex CLI client Execute Codex CLI: @@ -244,7 +244,7 @@ Requests will now be routed through WSO2 API Platform. ## Use case examples -### View API Analytics and Insights +### View API analytics and insights By routing Codex CLI requests through the WSO2 API Manager AI Gateway, you automatically gain access to built-in analytics and reporting capabilities. @@ -258,7 +258,7 @@ For more information on Analytics, refer to the official [WSO2 API Platform Docu --- -### Implement WSO2 AI Gateway Guardrails for Enhanced Control +### Implement WSO2 AI Gateway guardrails for enhanced control WSO2 API Manager AI Gateway guardrails enable granular control over the data exchanged between Codex CLI and the OpenAI API. @@ -272,7 +272,7 @@ For more information on AI Guardrails, refer to the official [WSO2 API Platform --- -### Rate Limiting at AI Gateway +### Rate limiting at AI Gateway WSO2 API Manager AI Gateway supports request-based and token-based rate limiting for AI APIs. This allows you to control Codex CLI usage when requests are routed through the Gateway. @@ -288,7 +288,7 @@ For more information on Rate Limiting and other policies, refer to the official --- -### Prompt Decorator +### Prompt decorator WSO2 API Manager AI Gateway supports Prompt Decorators, which allow you to modify or enrich prompts before they are sent to the backend AI provider. This is useful for enforcing consistent instructions, adding system-level context, or guiding model behavior without requiring changes in the client application. diff --git a/en/docs/cloud/ai-gateway/llm/ai-tools/gemini-cli-configuration-with-ai-gateway.md b/en/docs/cloud/ai-gateway/llm/ai-tools/gemini-cli-configuration-with-ai-gateway.md index 1b240fbe..62550e2e 100644 --- a/en/docs/cloud/ai-gateway/llm/ai-tools/gemini-cli-configuration-with-ai-gateway.md +++ b/en/docs/cloud/ai-gateway/llm/ai-tools/gemini-cli-configuration-with-ai-gateway.md @@ -47,7 +47,7 @@ Once the AI Gateway is active, you can continue to create the Gemini LLM provide --- -## Step 2: Create and Deploy a Gemini LLM Provider in AI Workspace Console +## Step 2: Create and deploy a Gemini LLM provider in AI Workspace console 1. Log in to the WSO2 API Platform Console as an admin. @@ -55,7 +55,7 @@ Once the AI Gateway is active, you can continue to create the Gemini LLM provide This opens the **AI Workspace Console**. -### Create a Gemini LLM Provider +### Create a Gemini LLM provider 1. In the left navigation panel of the AI Workspace Console, navigate to **LLM → LLM Providers**. @@ -69,7 +69,7 @@ This opens the **AI Workspace Console**. 6. Click **Add Provider**. -### Deploy the Gemini Provider to the AI Gateway +### Deploy the Gemini provider to the AI Gateway 1. On the page that opens after creating the provider, click **Deploy to Gateway**. @@ -81,7 +81,7 @@ The Gemini LLM provider is now deployed to the selected AI Gateway. --- -## Step 3: Create and Deploy an App LLM Proxy +## Step 3: Create and deploy an app LLM proxy The App LLM Proxy is the endpoint that Google Gemini CLI will invoke through WSO2 API Platform. @@ -117,7 +117,7 @@ The App LLM Proxy is the endpoint that Google Gemini CLI will invoke through WSO 12. Click **Create Proxy**. -### Configure the API Key Header for Google Gemini CLI +### Configure the API key header for Google Gemini CLI Google Gemini CLI sends its API key in a header named `x-goog-api-key`. The App LLM Proxy must be configured to accept this header. @@ -133,7 +133,7 @@ Google Gemini CLI sends its API key in a header named `x-goog-api-key`. The App x-goog-api-key ``` -### Deploy the App LLM Proxy to the AI Gateway +### Deploy the app LLM proxy to the AI Gateway 1. Click **Deploy to Gateway**. @@ -143,7 +143,7 @@ Google Gemini CLI sends its API key in a header named `x-goog-api-key`. The App The App LLM Proxy is now deployed to the selected AI Gateway. -### Generate an API Key for Gemini CLI +### Generate an API key for Gemini CLI Google Gemini CLI needs an API key from WSO2 API Platform to invoke the deployed App LLM Proxy. @@ -165,7 +165,7 @@ You will use these values when configuring Gemini CLI. --- -## Step 4: Configure Gemini CLI Environment Variables +## Step 4: Configure Gemini CLI environment variables Open a terminal session where you want to run Google Gemini CLI. @@ -189,7 +189,7 @@ Replace: !!! note These environment variables must be set in the same terminal session where Gemini CLI is executed. Alternatively, they can be configured as permanent environment variables. -### Configure SSL Certificate Trust +### Configure SSL certificate trust When using a local WSO2 API Platform AI Gateway over HTTPS, Gemini CLI must be able to trust the certificate presented by the Gateway. @@ -220,9 +220,9 @@ Google Gemini CLI will now send requests through WSO2 API Platform instead of di --- -## Use case Examples +## Use case examples -### View API Analytics and Insights +### View API analytics and insights By routing Gemini CLI requests through the WSO2 API Manager AI Gateway, you automatically gain access to built-in analytics and reporting capabilities. @@ -236,7 +236,7 @@ For more information on Analytics, refer to the official [WSO2 API Platform Docu --- -### Implement WSO2 AI Gateway Guardrails for Enhanced Control +### Implement WSO2 AI Gateway guardrails for enhanced control WSO2 API Manager AI Gateway guardrails enable granular control over the data exchanged between Gemini CLI and the Google Gemini API. @@ -266,7 +266,7 @@ For more information on Rate Limiting and other policies, refer to the official --- -### Multi-Model Routing +### Multi-model routing WSO2 API Manager AI Gateway supports multi-model routing, allowing you to dynamically route requests to different AI models based on defined conditions or strategies. @@ -286,7 +286,7 @@ For more information on Multi-Model Routing, refer to the official [WSO2 API Pla --- -### Prompt Decorator +### Prompt decorator WSO2 API Manager AI Gateway supports Prompt Decorators, which allow you to modify or enrich prompts before they are sent to the backend AI provider. This is useful for enforcing consistent instructions, adding system-level context, or guiding model behavior without requiring changes in the client application. diff --git a/en/docs/cloud/ai-gateway/llm/guardrails/aws-bedrock-guardrail.md b/en/docs/cloud/ai-gateway/llm/guardrails/aws-bedrock-guardrail.md index 294e0510..644e4b26 100644 --- a/en/docs/cloud/ai-gateway/llm/guardrails/aws-bedrock-guardrail.md +++ b/en/docs/cloud/ai-gateway/llm/guardrails/aws-bedrock-guardrail.md @@ -1,4 +1,4 @@ -# AWS Bedrock Guardrail +# AWS Bedrock guardrail ## Overview @@ -23,7 +23,7 @@ The policy supports multiple authentication modes including AWS IAM role assumpt ### Parameters -#### Request Phase +#### Request phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -32,7 +32,7 @@ The policy supports multiple authentication modes including AWS IAM role assumpt | `passthroughOnError` | boolean | No | `false` | If `true`, allows requests to proceed if AWS Bedrock Guardrail API call fails. If `false`, blocks requests on API errors. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information from AWS Bedrock Guardrail in error responses. | -#### Response Phase +#### Response phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -40,7 +40,7 @@ The policy supports multiple authentication modes including AWS IAM role assumpt | `passthroughOnError` | boolean | No | `false` | If `true`, allows requests to proceed if AWS Bedrock Guardrail API call fails. If `false`, blocks requests on API errors. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information from AWS Bedrock Guardrail in error responses. | -### System Parameters (Required) +### System parameters (required) These parameters are typically configured at the gateway level and automatically injected, or you can override those values from the params section in the api artifact definition file as well: @@ -57,7 +57,7 @@ These parameters are typically configured at the gateway level and automatically | `awsRoleExternalID` | string | No | External ID for role assumption (optional, for cross-account access security). | -### Configuring System Parameters in config.toml +### Configuring system parameters in config.toml System parameters can be configured globally in the gateway's `config.toml` file. These values serve as defaults for all AWS Bedrock Guardrail policy instances and can be overridden per-policy in the API configuration if needed. @@ -77,7 +77,7 @@ awsbedrock_role_region = "" awsbedrock_role_external_id = "" ``` -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and validate specific fields within JSON payloads. Common examples: @@ -89,15 +89,15 @@ The guardrail supports JSONPath expressions to extract and validate specific fie If `jsonPath` is empty or not specified, the entire payload is treated as a string and validated. -## PII Handling +## PII handling -### Masking Mode (redactPII: false) +### Masking mode (redactpii: false) When `redactPII` is `false`: - **Request phase**: PII entities are masked with placeholders like `EMAIL_0001`, `PHONE_0002`, etc. - Use this mode when you need PII to flow through the system but want it masked during processing -### Redaction Mode (redactPII: true) +### Redaction mode (redactpii: true) When `redactPII` is `true`: - PII entities are permanently replaced with `*****` @@ -106,7 +106,7 @@ When `redactPII` is `true`: ## Examples -### Example 1: Basic Guardrail with Static Credentials +### Example 1: Basic guardrail with static credentials Deploy an LLM provider with AWS Bedrock Guardrail validation: @@ -188,7 +188,7 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Example 2: PII Redaction Mode +### Example 2: PII redaction mode Configure to redact PII: @@ -208,7 +208,7 @@ policies: jsonPath: "$.choices[0].message.content" ``` -## Use Cases +## Use cases 1. **Content Safety**: Enforce enterprise content policies to prevent inappropriate or harmful content from being processed or returned. @@ -224,7 +224,7 @@ policies: 7. **Audit and Monitoring**: Use detailed assessment information to audit content violations and improve policies. -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: diff --git a/en/docs/cloud/ai-gateway/llm/guardrails/azure-content-safety.md b/en/docs/cloud/ai-gateway/llm/guardrails/azure-content-safety.md index 22c61173..0fdf6aac 100644 --- a/en/docs/cloud/ai-gateway/llm/guardrails/azure-content-safety.md +++ b/en/docs/cloud/ai-gateway/llm/guardrails/azure-content-safety.md @@ -21,7 +21,7 @@ The policy uses Azure Content Safety's text analysis API to evaluate content and ### Parameters -#### Request Phase +#### Request phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -33,7 +33,7 @@ The policy uses Azure Content Safety's text analysis API to evaluate content and | `selfHarmCategory` | integer | No | `-1` | Severity threshold for self-harm category (0-7). `-1` disables this category. Content with severity >= threshold will be blocked. | | `violenceCategory` | integer | No | `-1` | Severity threshold for violence category (0-7). `-1` disables this category. Content with severity >= threshold will be blocked. | -#### Response Phase +#### Response phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -45,7 +45,7 @@ The policy uses Azure Content Safety's text analysis API to evaluate content and | `selfHarmCategory` | integer | No | `-1` | Severity threshold for self-harm category (0-7). `-1` disables this category. Content with severity >= threshold will be blocked. | | `violenceCategory` | integer | No | `-1` | Severity threshold for violence category (0-7). `-1` disables this category. Content with severity >= threshold will be blocked. | -### System Parameters (Required) +### System parameters (required) These parameters are typically configured at the gateway level and automatically injected, or you can override those values from the params section in the api artifact definition file as well: @@ -54,7 +54,7 @@ These parameters are typically configured at the gateway level and automatically | `azureContentSafetyEndpoint` | string | Yes | Azure Content Safety API endpoint URL (without trailing slash). Example: `https://your-resource.cognitiveservices.azure.com` | | `azureContentSafetyKey` | string | Yes | Azure Content Safety API subscription key for authentication. Found in Azure Portal under your Content Safety resource's "Keys and Endpoint" section. | -### Configuring System Parameters in config.toml +### Configuring system parameters in config.toml System parameters can be configured globally in the gateway's `config.toml` file. These values serve as defaults for all Azure Content Safety guardrail policy instances and can be overridden per-policy in the API configuration if needed. @@ -67,7 +67,7 @@ azurecontentsafety_endpoint = "https://your-resource.cognitiveservices.azure.com azurecontentsafety_key = "" ``` -## Severity Levels +## Severity levels Azure Content Safety uses an 8-level severity scale (0-7): @@ -77,12 +77,12 @@ Azure Content Safety uses an 8-level severity scale (0-7): - **5-6**: High severity - Highly concerning content - **7**: Maximum severity - Most severe harmful content -**Threshold Configuration**: +**Threshold configuration**: - Set a threshold value (0-7) to block content at or above that severity level - Set to `-1` to disable monitoring for that category - Example: `hateCategory: 3` blocks content with hate severity >= 3 -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and validate specific fields within JSON payloads. Common examples: @@ -97,7 +97,7 @@ If `jsonPath` is empty or not specified, the entire payload is treated as a stri ## Examples -### Example 1: Basic Content Moderation +### Example 1: Basic content moderation Deploy an LLM provider with Azure Content Safety validation: @@ -186,7 +186,7 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Example 2: Strict Moderation with All Categories +### Example 2: Strict moderation with all categories Configure strict moderation thresholds: @@ -215,7 +215,7 @@ policies: showAssessment: true ``` -### Example 3: Selective Category Monitoring +### Example 3: Selective category monitoring Monitor only specific categories: @@ -235,7 +235,7 @@ policies: violenceCategory: -1 # Disabled ``` -### Example 4: Lenient Moderation +### Example 4: Lenient moderation Allow more content with higher thresholds: @@ -256,32 +256,32 @@ policies: passthroughOnError: true ``` -## Use Cases +## Use cases -1. **Content Safety**: Protect users from harmful, offensive, or inappropriate content in LLM interactions. +1. **Content safety**: Protect users from harmful, offensive, or inappropriate content in LLM interactions. -2. **Regulatory Compliance**: Meet content moderation requirements for regulated industries or geographies. +2. **Regulatory compliance**: Meet content moderation requirements for regulated industries or geographies. -3. **Brand Safety**: Ensure LLM responses align with brand values and don't generate problematic content. +3. **Brand safety**: Ensure LLM responses align with brand values and don't generate problematic content. -4. **User Protection**: Prevent exposure to self-harm content, especially important for mental health applications. +4. **User protection**: Prevent exposure to self-harm content, especially important for mental health applications. -5. **Community Guidelines**: Enforce community standards for user-generated content processed through LLMs. +5. **Community guidelines**: Enforce community standards for user-generated content processed through LLMs. -6. **Multi-tenant Applications**: Apply different moderation policies per tenant or application context. +6. **Multi-tenant applications**: Apply different moderation policies per tenant or application context. -7. **Gradual Rollout**: Start with lenient thresholds and tighten based on actual content patterns. +7. **Gradual rollout**: Start with lenient thresholds and tighten based on actual content patterns. -8. **Audit and Analytics**: Use detailed assessment information to analyze content patterns and refine policies. +8. **Audit and analytics**: Use detailed assessment information to analyze content patterns and refine policies. -## Severity Threshold Guidelines +## Severity threshold guidelines **Recommended thresholds by use case**: - **Strict (Family-friendly applications)**: 1-2 across all categories - **Moderate (General business applications)**: 3-4 across all categories - **Lenient (Technical/professional contexts)**: 5-6 for most categories, disable non-applicable ones -- **Educational/Research**: 4-5 with selective category monitoring +- **Educational/research**: 4-5 with selective category monitoring **Category-specific considerations**: @@ -290,7 +290,7 @@ policies: - **Self-harm**: Often set lower (1-2) due to safety concerns - **Violence**: Depends on context (1-2 for general use, higher for educational/historical content) -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: diff --git a/en/docs/cloud/ai-gateway/llm/guardrails/content-length.md b/en/docs/cloud/ai-gateway/llm/guardrails/content-length.md index c7f52200..d3caa5ea 100644 --- a/en/docs/cloud/ai-gateway/llm/guardrails/content-length.md +++ b/en/docs/cloud/ai-gateway/llm/guardrails/content-length.md @@ -1,4 +1,4 @@ -# Content Length Guardrail +# Content length guardrail ## Overview @@ -16,7 +16,7 @@ The Content Length Guardrail validates the byte length of request or response bo ### Parameters -#### Request Phase +#### Request phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -26,7 +26,7 @@ The Content Length Guardrail validates the byte length of request or response bo | `invert` | boolean | No | `false` | If `true`, validation passes when content length is NOT within the min-max range. If `false`, validation passes when content length is within the range. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information in error responses. | -#### Response Phase +#### Response phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -36,7 +36,7 @@ The Content Length Guardrail validates the byte length of request or response bo | `invert` | boolean | No | `false` | If `true`, validation passes when content length is NOT within the min-max range. If `false`, validation passes when content length is within the range. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information in error responses. | -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and validate specific fields within JSON payloads. Common examples: @@ -49,7 +49,7 @@ If `jsonPath` is empty or not specified, the entire payload is treated as a stri ## Examples -### Example 1: Basic Content Length Validation +### Example 1: Basic content length validation Deploy an LLM provider that limits request payloads to between 100 bytes and 1MB: @@ -131,31 +131,31 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Additional Configuration Options +### Additional configuration options You can customize the guardrail behavior by modifying the `policies` section: -- **Request and Response Validation**: Configure both `request` and `response` parameters to validate byte lengths in both directions. Use `showAssessment: true` to include detailed assessment information in error responses. +- **Request and response validation**: Configure both `request` and `response` parameters to validate byte lengths in both directions. Use `showAssessment: true` to include detailed assessment information in error responses. -- **Inverted Logic**: Set `invert: true` to allow only content *outside* the specified byte range. This is useful for blocking content that falls within a prohibited size range. +- **Inverted logic**: Set `invert: true` to allow only content *outside* the specified byte range. This is useful for blocking content that falls within a prohibited size range. -- **Full Payload Validation**: Omit the `jsonPath` parameter to validate the entire request body without JSONPath extraction. +- **Full payload validation**: Omit the `jsonPath` parameter to validate the entire request body without JSONPath extraction. -- **Field-Specific Validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). +- **Field-specific validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). -## Use Cases +## Use cases -1. **Resource Protection**: Prevent excessively large payloads that could exhaust system resources or cause performance degradation. +1. **Resource protection**: Prevent excessively large payloads that could exhaust system resources or cause performance degradation. -2. **Network Optimization**: Control payload sizes to optimize network transfer times and reduce bandwidth costs. +2. **Network optimization**: Control payload sizes to optimize network transfer times and reduce bandwidth costs. -3. **Storage Management**: Limit content sizes to manage storage requirements effectively. +3. **Storage management**: Limit content sizes to manage storage requirements effectively. -4. **API Rate Limiting**: Enforce size constraints as part of rate limiting strategies. +4. **API rate limiting**: Enforce size constraints as part of rate limiting strategies. -5. **Quality Assurance**: Ensure responses meet minimum size requirements for completeness. +5. **Quality assurance**: Ensure responses meet minimum size requirements for completeness. -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: diff --git a/en/docs/cloud/ai-gateway/llm/guardrails/json-schema.md b/en/docs/cloud/ai-gateway/llm/guardrails/json-schema.md index 292568e9..aaaf7887 100644 --- a/en/docs/cloud/ai-gateway/llm/guardrails/json-schema.md +++ b/en/docs/cloud/ai-gateway/llm/guardrails/json-schema.md @@ -1,4 +1,4 @@ -# JSON Schema Guardrail +# JSON schema guardrail ## Overview @@ -16,7 +16,7 @@ The JSON Schema Guardrail validates request or response body content against a J ### Parameters -#### Request Phase +#### Request phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -25,7 +25,7 @@ The JSON Schema Guardrail validates request or response body content against a J | `invert` | boolean | No | `false` | If `true`, validation passes when schema validation FAILS. If `false`, validation passes when schema validation succeeds. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed validation error information in error responses. | -#### Response Phase +#### Response phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -34,7 +34,7 @@ The JSON Schema Guardrail validates request or response body content against a J | `invert` | boolean | No | `false` | If `true`, validation passes when schema validation FAILS. If `false`, validation passes when schema validation succeeds. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed validation error information in error responses. | -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and validate specific fields within JSON payloads. Common examples: @@ -45,20 +45,20 @@ The guardrail supports JSONPath expressions to extract and validate specific fie If `jsonPath` is empty or not specified, the entire payload is validated against the schema. -## JSON Schema Features +## JSON schema features The guardrail supports JSON Schema Draft 7, including: - **Types**: `string`, `number`, `integer`, `boolean`, `object`, `array`, `null` - **Properties**: Define object properties and their schemas -- **Required Fields**: Specify which properties are mandatory +- **Required fields**: Specify which properties are mandatory - **Constraints**: `minLength`, `maxLength`, `minimum`, `maximum`, `pattern`, `enum` -- **Nested Structures**: Complex nested objects and arrays -- **Conditional Logic**: `if`, `then`, `else`, `allOf`, `anyOf`, `oneOf`, `not` +- **Nested structures**: Complex nested objects and arrays +- **Conditional logic**: `if`, `then`, `else`, `allOf`, `anyOf`, `oneOf`, `not` ## Examples -### Example 1: Basic Object Validation +### Example 1: Basic object validation Deploy an LLM provider that validates that request contains a user object with required fields: @@ -151,23 +151,23 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Additional Configuration Options +### Additional configuration options You can customize the guardrail behavior by modifying the `policies` section: -- **Request and Response Validation**: Configure both `request` and `response` parameters to validate JSON schemas in both directions. Use `showAssessment: true` to include detailed validation error information in error responses. +- **Request and response validation**: Configure both `request` and `response` parameters to validate JSON schemas in both directions. Use `showAssessment: true` to include detailed validation error information in error responses. -- **Inverted Logic**: Set `invert: true` to allow only content that does *not* match the schema. This is useful for blocking requests that match specific schema patterns. +- **Inverted logic**: Set `invert: true` to allow only content that does *not* match the schema. This is useful for blocking requests that match specific schema patterns. -- **Full Payload Validation**: Omit the `jsonPath` parameter to validate the entire request body against the schema. +- **Full payload validation**: Omit the `jsonPath` parameter to validate the entire request body against the schema. -- **Field-Specific Validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0]"` for message objects or `"$.results"` for response arrays). +- **Field-specific validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0]"` for message objects or `"$.results"` for response arrays). -## Use Cases +## Use cases -1. **API Contract Enforcement**: Ensure requests and responses conform to API specifications. +1. **API contract enforcement**: Ensure requests and responses conform to API specifications. -2. **Data Quality**: Validate data structure and types before processing. +2. **Data quality**: Validate data structure and types before processing. 3. **Security**: Enforce required fields and prevent injection of unexpected data structures. @@ -175,7 +175,7 @@ You can customize the guardrail behavior by modifying the `policies` section: 5. **Compliance**: Enforce data formats required by regulatory standards. -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: diff --git a/en/docs/cloud/ai-gateway/llm/guardrails/pii-masking-regex.md b/en/docs/cloud/ai-gateway/llm/guardrails/pii-masking-regex.md index 25db7b42..c751e597 100644 --- a/en/docs/cloud/ai-gateway/llm/guardrails/pii-masking-regex.md +++ b/en/docs/cloud/ai-gateway/llm/guardrails/pii-masking-regex.md @@ -1,4 +1,4 @@ -# PII Masking Regex Guardrail +# PII masking regex guardrail ## Overview @@ -21,7 +21,7 @@ The PII Masking Regex Guardrail masks or redacts Personally Identifiable Informa | `jsonPath` | string | No | `""` | JSONPath expression to extract a specific value from JSON payload. If empty, processes the entire payload as a string. | | `redactPII` | boolean | No | `false` | If `true`, redacts PII by replacing with "*****" (permanent, cannot be restored). If `false`, masks PII with placeholders that can be restored in responses. | -### PII Entity Configuration +### PII entity configuration Each PII entity in the `piiEntities` array must contain: @@ -30,7 +30,7 @@ Each PII entity in the `piiEntities` array must contain: | `piiEntity` | string | Yes | Name/type of the PII entity (e.g., "EMAIL", "PHONE", "SSN", "CREDIT_CARD"). Must contain only uppercase letters and underscores (matches `^[A-Z_]+$`). | | `piiRegex` | string | Yes | Regular expression pattern to match the PII entity. Must be a valid Go regexp pattern. | -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and process specific fields within JSON payloads. Common examples: @@ -41,16 +41,16 @@ The guardrail supports JSONPath expressions to extract and process specific fiel If `jsonPath` is empty or not specified, the entire payload is processed as a string. -## PII Masking Modes +## PII masking modes -### Masking Mode (`redactPII: false`) +### Masking mode (`redactpii: false`) - PII is replaced with placeholders in the format `[ENTITY_TYPE_XXXX]` where XXXX is a 4-digit hexadecimal number (e.g., `[EMAIL_0000]`, `[EMAIL_0001]`, `[PHONE_000a]`) - Placeholders are automatically restored in responses to their original values - Original PII values are stored temporarily in request metadata for restoration - Recommended when you need to preserve data for downstream processing or response generation -### Redaction Mode (`redactPII: true`) +### Redaction mode (`redactpii: true`) - PII is permanently replaced with "*****" - Cannot be restored in responses @@ -59,7 +59,7 @@ If `jsonPath` is empty or not specified, the entire payload is processed as a st ## Examples -### Example 1: Basic PII Masking +### Example 1: Basic PII masking Deploy an LLM provider that masks email addresses and phone numbers in requests and restores them in responses: @@ -131,35 +131,35 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Additional Configuration Options +### Additional configuration options You can customize the guardrail behavior by modifying the `policies` section: -- **PII Redaction**: Set `redactPII: true` to permanently replace PII with "*****" (cannot be restored). Set `redactPII: false` to use masking mode with placeholders that can be restored in responses. +- **PII redaction**: Set `redactPII: true` to permanently replace PII with "*****" (cannot be restored). Set `redactPII: false` to use masking mode with placeholders that can be restored in responses. -- **Multiple PII Types**: Configure multiple `piiEntities` in the array to detect and mask/redact various PII types (e.g., EMAIL, PHONE, CREDIT_CARD, SSN, IP_ADDRESS, DATE_OF_BIRTH). +- **Multiple PII types**: Configure multiple `piiEntities` in the array to detect and mask/redact various PII types (e.g., EMAIL, PHONE, CREDIT_CARD, SSN, IP_ADDRESS, DATE_OF_BIRTH). -- **Full Payload Processing**: Omit the `jsonPath` parameter to process the entire request body without JSONPath extraction. +- **Full payload processing**: Omit the `jsonPath` parameter to process the entire request body without JSONPath extraction. -- **Field-Specific Processing**: Use `jsonPath` to extract and process PII from specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content). +- **Field-specific processing**: Use `jsonPath` to extract and process PII from specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content). -- **Response Restoration**: When using masking mode (`redactPII: false`), PII is automatically restored in responses. No separate response configuration is needed. If `redactPII: true`, no restoration occurs in the response phase. +- **Response restoration**: When using masking mode (`redactPII: false`), PII is automatically restored in responses. No separate response configuration is needed. If `redactPII: true`, no restoration occurs in the response phase. -## Use Cases +## Use cases -1. **Privacy Protection**: Mask or redact PII before sending data to AI services or external systems. +1. **Privacy protection**: Mask or redact PII before sending data to AI services or external systems. 2. **Compliance**: Meet regulatory requirements (GDPR, CCPA, HIPAA) for PII handling. -3. **Data Minimization**: Reduce exposure of sensitive data in logs, analytics, or third-party integrations. +3. **Data minimization**: Reduce exposure of sensitive data in logs, analytics, or third-party integrations. -4. **Secure Processing**: Allow AI processing while protecting user privacy through masking. +4. **Secure processing**: Allow AI processing while protecting user privacy through masking. -5. **Audit Trail**: Maintain masked versions of data for auditing while protecting original values. +5. **Audit trail**: Maintain masked versions of data for auditing while protecting original values. -## How It Works +## How it works -### Request Phase (Masking) +### Request phase (masking) 1. Extract content using JSONPath (if specified) or use entire payload 2. Apply each PII regex pattern to find matches @@ -167,7 +167,7 @@ You can customize the guardrail behavior by modifying the `policies` section: 4. Store mapping of placeholders to original values (for masking mode) 5. Forward masked content to upstream service -### Response Phase (Restoration) +### Response phase (restoration) 1. Check if PII was masked in the request phase (metadata contains PII mappings) 2. If `redactPII: false` and mappings exist, replace placeholders with original PII values @@ -175,7 +175,7 @@ You can customize the guardrail behavior by modifying the `policies` section: 4. Return restored content or original response -#### Sample Payload after intervention from Regex PII Masking with redact=true +#### Sample payload after intervention from regex PII masking with redact=true ``` { diff --git a/en/docs/cloud/ai-gateway/llm/guardrails/regex.md b/en/docs/cloud/ai-gateway/llm/guardrails/regex.md index af6e7205..80eb4683 100644 --- a/en/docs/cloud/ai-gateway/llm/guardrails/regex.md +++ b/en/docs/cloud/ai-gateway/llm/guardrails/regex.md @@ -1,4 +1,4 @@ -# Regex Guardrail +# Regex guardrail ## Overview @@ -16,7 +16,7 @@ The Regex Guardrail validates request or response body content against regular e ### Parameters -#### Request Phase +#### Request phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -25,7 +25,7 @@ The Regex Guardrail validates request or response body content against regular e | `invert` | boolean | No | `false` | If `true`, validation passes when regex does NOT match. If `false`, validation passes when regex matches. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information in error responses. | -#### Response Phase +#### Response phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -34,7 +34,7 @@ The Regex Guardrail validates request or response body content against regular e | `invert` | boolean | No | `false` | If `true`, validation passes when regex does NOT match. If `false`, validation passes when regex matches. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information in error responses. | -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and validate specific fields within JSON payloads. Common examples: @@ -45,7 +45,7 @@ The guardrail supports JSONPath expressions to extract and validate specific fie If `jsonPath` is empty or not specified, the entire payload is treated as a string and validated. -## Regular Expression Syntax +## Regular expression syntax The guardrail uses Go's standard regexp package, which supports RE2 syntax. Key features: @@ -58,7 +58,7 @@ The guardrail uses Go's standard regexp package, which supports RE2 syntax. Key ## Examples -### Example 1: Email Validation +### Example 1: Email validation Deploy an LLM provider that protects against sensitive data leaks by blocking any payloads that mention the word "password" (case-insensitive) in either the user’s message or the LLM’s response. This is achieved by using the regex policy to validate both request and response payloads: @@ -141,31 +141,31 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Additional Configuration Options +### Additional configuration options You can customize the guardrail behavior by modifying the `policies` section: -- **Request and Response Validation**: Configure both `request` and `response` parameters to validate patterns in both directions. Use `showAssessment: true` to include detailed assessment information in error responses. +- **Request and response validation**: Configure both `request` and `response` parameters to validate patterns in both directions. Use `showAssessment: true` to include detailed assessment information in error responses. -- **Inverted Logic**: Set `invert: true` to allow only content that does *not* match the regex pattern. This is useful for blocking prohibited patterns (e.g., password-related content, admin keywords). +- **Inverted logic**: Set `invert: true` to allow only content that does *not* match the regex pattern. This is useful for blocking prohibited patterns (e.g., password-related content, admin keywords). -- **Full Payload Validation**: Omit the `jsonPath` parameter to validate the entire request body without JSONPath extraction. +- **Full payload validation**: Omit the `jsonPath` parameter to validate the entire request body without JSONPath extraction. -- **Field-Specific Validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). +- **Field-specific validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). -## Use Cases +## Use cases -1. **Format Validation**: Ensure user inputs match expected formats (emails, phone numbers, IDs). +1. **Format validation**: Ensure user inputs match expected formats (emails, phone numbers, IDs). -2. **Content Filtering**: Block or allow content based on pattern matching (prohibited words, sensitive patterns). +2. **Content filtering**: Block or allow content based on pattern matching (prohibited words, sensitive patterns). -3. **Security Enforcement**: Detect and block potentially malicious patterns or injection attempts. +3. **Security enforcement**: Detect and block potentially malicious patterns or injection attempts. -4. **Data Quality**: Ensure responses follow specific formatting requirements or contain required elements. +4. **Data quality**: Ensure responses follow specific formatting requirements or contain required elements. 5. **Compliance**: Enforce patterns required by regulatory standards or business rules. -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: diff --git a/en/docs/cloud/ai-gateway/llm/guardrails/semantic-prompt-guard.md b/en/docs/cloud/ai-gateway/llm/guardrails/semantic-prompt-guard.md index 65984fdc..afeed26b 100644 --- a/en/docs/cloud/ai-gateway/llm/guardrails/semantic-prompt-guard.md +++ b/en/docs/cloud/ai-gateway/llm/guardrails/semantic-prompt-guard.md @@ -1,4 +1,4 @@ -# Semantic Prompt Guardrail +# Semantic prompt guardrail ## Overview @@ -15,15 +15,15 @@ The policy uses embedding models (OpenAI, Mistral, or Azure OpenAI) to convert p - **JSONPath extraction**: Extract specific fields from request body for validation - **Detailed assessment information**: Optional detailed violation information in error responses -## How It Works +## How it works -1. **Text Extraction**: Extracts prompt text from the request body using JSONPath (if configured) or uses the entire request body -2. **Embedding Generation**: Generates a vector embedding from the extracted prompt using the configured embedding provider -3. **Validation Strategy**: The validation logic depends on which lists are configured: +1. **Text extraction**: Extracts prompt text from the request body using JSONPath (if configured) or uses the entire request body +2. **Embedding generation**: Generates a vector embedding from the extracted prompt using the configured embedding provider +3. **Validation strategy**: The validation logic depends on which lists are configured: - **Deny list only**: Compares prompt embedding against all denied phrases. If any denied phrase has similarity >= `denySimilarityThreshold`, the request is blocked. Otherwise, it proceeds. - **Allow list only**: Compares prompt embedding against all allowed phrases. If no allowed phrase has similarity >= `allowSimilarityThreshold`, the request is blocked. Otherwise, it proceeds. - **Both lists**: First checks the deny list (blocks if similarity >= `denySimilarityThreshold`), then checks the allow list (blocks if similarity < `allowSimilarityThreshold`). Request proceeds only if it passes both checks. -4. **Validation Result**: Request proceeds if validation passes, or is blocked with HTTP 422 if validation fails +4. **Validation result**: Request proceeds if validation passes, or is blocked with HTTP 422 if validation fails ## Configuration @@ -40,7 +40,7 @@ The policy uses embedding models (OpenAI, Mistral, or Azure OpenAI) to convert p \* At least one of `allowedPhrases` or `deniedPhrases` must be provided. -### System Parameters (Required) +### System parameters (required) These parameters are typically configured at the gateway level and automatically injected, or you can override those values from the params section in the api artifact definition file as well: @@ -51,7 +51,7 @@ These parameters are typically configured at the gateway level and automatically | `embeddingModel` | string | Conditional | - | Embedding model name. **Required for OPENAI and MISTRAL**, not required for AZURE_OPENAI (deployment name is in endpoint URL). Examples: OpenAI: `text-embedding-ada-002` or `text-embedding-3-small`, Mistral: `mistral-embed` | | `apiKey` | string | Yes | API key for the embedding service authentication | -### Configuring System Parameters in config.toml +### Configuring system parameters in config.toml System parameters can be configured globally in the gateway's `config.toml` file. These values serve as defaults for all Semantic Prompt Guard policy instances and can be overridden per-policy in the API configuration if needed. @@ -67,11 +67,11 @@ embedding_provider_dimension = 1024 embedding_provider_api_key = "" ``` -## Similarity Threshold Guidelines +## Similarity threshold guidelines The similarity thresholds control how similar prompts must be to trigger allow/deny decisions: -### Allow Similarity Threshold +### Allow similarity threshold - **0.95-1.0**: Very strict matching. Only near-identical prompts to allowed phrases will pass. Use for exact-match scenarios. - **0.85-0.94**: Recommended for most use cases. Catches semantically equivalent prompts with some wording variation. @@ -81,7 +81,7 @@ The similarity thresholds control how similar prompts must be to trigger allow/d **Recommendation**: Start with 0.65 and adjust based on your use case. Monitor false positives/negatives to fine-tune. -### Deny Similarity Threshold +### Deny similarity threshold - **0.95-1.0**: Very strict blocking. Only near-identical prompts to denied phrases will be blocked. - **0.85-0.94**: Recommended for most use cases. Catches semantically equivalent prompts with some wording variation. @@ -91,14 +91,14 @@ The similarity thresholds control how similar prompts must be to trigger allow/d **Recommendation**: Start with 0.65 and adjust based on your use case. Monitor false positives to fine-tune. -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract specific text from request bodies before validation. This is useful for: - Extracting message content from chat completion requests - Focusing on specific prompt fields while ignoring metadata - Handling structured JSON payloads -### Common JSONPath Examples +### Common jsonpath examples - `$.messages[0].content` - First message's content in chat completions - `$.messages[-1].content` - Last message's content @@ -108,7 +108,7 @@ The guardrail supports JSONPath expressions to extract specific text from reques ## Examples -### Example 1: Deny List Only - Blocking Prohibited Content +### Example 1: Deny list only - blocking prohibited content Deploy an LLM provider that blocks prompts similar to prohibited phrases: @@ -190,7 +190,7 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Example 2: Allow List Only - Whitelist Approach +### Example 2: Allow list only - whitelist approach Deploy an LLM provider that only allows prompts similar to approved phrases: @@ -236,7 +236,7 @@ spec: EOF ``` -### Example 3: Combined Allow and Deny Lists +### Example 3: Combined allow and deny lists Use both allow and deny lists for comprehensive filtering: @@ -262,7 +262,7 @@ policies: showAssessment: true ``` -### Example 4: Azure OpenAI with Custom Timeout +### Example 4: Azure OpenAI with custom timeout Configure semantic prompt guardrail with Azure OpenAI and extended timeout: @@ -281,25 +281,25 @@ policies: - "Another prohibited phrase" ``` -## Use Cases +## Use cases -1. **Content Safety**: Block prompts that are semantically similar to prohibited content, even when exact keywords differ. +1. **Content safety**: Block prompts that are semantically similar to prohibited content, even when exact keywords differ. -2. **Whitelist Filtering**: Only allow prompts that match approved use cases or topics, ensuring LLM usage stays within defined boundaries. +2. **Whitelist filtering**: Only allow prompts that match approved use cases or topics, ensuring LLM usage stays within defined boundaries. 3. **Compliance**: Enforce content policies by blocking prompts similar to non-compliant examples. -4. **Abuse Prevention**: Detect and block variations of known abuse patterns, even when attackers try to evade keyword filters. +4. **Abuse prevention**: Detect and block variations of known abuse patterns, even when attackers try to evade keyword filters. -5. **Domain Restriction**: Restrict LLM usage to specific domains by allowing only prompts similar to approved domain-specific phrases. +5. **Domain restriction**: Restrict LLM usage to specific domains by allowing only prompts similar to approved domain-specific phrases. -6. **Multi-tenant Security**: Apply different allow/deny lists per tenant or application to enforce tenant-specific content policies. +6. **Multi-tenant security**: Apply different allow/deny lists per tenant or application to enforce tenant-specific content policies. -7. **Prompt Injection Prevention**: Block prompts that are semantically similar to known prompt injection attacks. +7. **Prompt injection prevention**: Block prompts that are semantically similar to known prompt injection attacks. -8. **Quality Control**: Ensure prompts match expected patterns for better response quality and consistency. +8. **Quality control**: Ensure prompts match expected patterns for better response quality and consistency. -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: @@ -359,15 +359,15 @@ For errors during processing (e.g., JSONPath extraction failures, embedding gene } ``` -## Performance Considerations +## Performance considerations -1. **Embedding Generation Latency**: Generating embeddings adds ~100-500ms to request processing. This is a one-time cost per request. +1. **Embedding generation latency**: Generating embeddings adds ~100-500ms to request processing. This is a one-time cost per request. -2. **Batch Processing**: All allow/deny phrase embeddings are generated in a single batch during policy initialization, minimizing initialization overhead. +2. **Batch processing**: All allow/deny phrase embeddings are generated in a single batch during policy initialization, minimizing initialization overhead. -3. **Similarity Calculation**: Cosine similarity calculations are fast (typically < 10ms) even with many phrases. +3. **Similarity calculation**: Cosine similarity calculations are fast (typically < 10ms) even with many phrases. -4. **Embedding Provider Selection**: +4. **Embedding provider selection**: - OpenAI: Fast, reliable, good for most use cases - Mistral: Alternative option with good performance - Azure OpenAI: Good for Azure-integrated environments diff --git a/en/docs/cloud/ai-gateway/llm/guardrails/semantic-tool-filtering.md b/en/docs/cloud/ai-gateway/llm/guardrails/semantic-tool-filtering.md index e35206fb..0f27105f 100644 --- a/en/docs/cloud/ai-gateway/llm/guardrails/semantic-tool-filtering.md +++ b/en/docs/cloud/ai-gateway/llm/guardrails/semantic-tool-filtering.md @@ -2,7 +2,7 @@ title: "Overview" --- -# Semantic Tool Filtering policy +# Semantic tool filtering policy ## Overview The **Semantic Tool Filtering** policy dynamically filters the tools provided within an API request based on their semantic relevance to the user query. This policy extracts both the query and the tool definitions from the incoming payload, generates embeddings for the query, and performs a similarity search against the provided tools. It then replaces the original tools array with a filtered subset, optimizing the request before it reaches the LLM. @@ -12,14 +12,14 @@ This policy helps reduce token consumption and improve LLM response quality by s ## Features - **Semantic similarity-based filtering** of tools using embedding vectors. - **Two selection modes**: "By Rank" (top-K) and "By Threshold". -- **Flexible Format Support**: Supports both JSON and text-based tool/query extraction. +- **Flexible format support**: Supports both JSON and text-based tool/query extraction. - **Embedding cache** with LRU eviction to minimize redundant API calls. - **Configurable JSONPath expressions** for payload extraction. - **Mixed mode support** (extract query from JSON and tools from text, or vice versa). ## Configuration -### User Parameters (API Definition) +### User parameters (API definition) | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -31,7 +31,7 @@ This policy helps reduce token consumption and improve LLM response quality by s | userQueryIsJson | boolean | Yes | `true` | Specifies format of user query. `true`: use `queryJSONPath`. `false`: extract from text using `` tags. | | toolsIsJson | boolean | Yes | `true` | Specifies format of tools definition. `true`: use `toolsJSONPath`. `false`: extract from text using ``/`` tags. | -### System Parameters (From config.toml) +### System parameters (from config.toml) These parameters are configured in the gateway's `config.toml` to set up the embedding provider. @@ -42,7 +42,7 @@ These parameters are configured in the gateway's `config.toml` to set up the emb | embeddingModel | string | Conditional | - | Model name (e.g., `text-embedding-3-small` or `mistral-embed`). Required for `OPENAI` and `MISTRAL`; optional for `AZURE_OPENAI` (deployment name is derived from the endpoint). | | apiKey | string | Yes | - | API key for the embedding service. | -#### Sample System Configuration +#### Sample system configuration Add the following configuration section under the root level in your `config.toml` file: @@ -63,9 +63,9 @@ Add the following entry to the `policies` section in `/gateway/build.yaml`: gomodule: github.com/wso2/gateway-controllers/policies/semantic-tool-filtering@v0 ``` -## Reference Scenarios +## Reference scenarios -### Scenario 1: Filtering Tools by Rank (JSON Format) +### Scenario 1: Filtering tools by rank (JSON format) This scenario demonstrates filtering tools to select the top 3 most relevant ones based on a user query in a JSON payload. @@ -124,7 +124,7 @@ policies: The policy will interpret the request, calculate embeddings, and filter the `tools` array to include only the top 3 matches (e.g., `get_weather`, `book_venue`, `send_email`). -### Scenario 1b: OpenAI/Mistral-style Function Wrappers +### Scenario 1b: OpenAI/Mistral-style function wrappers If the request wraps each tool as an object with a nested `function`, configure the iterator path so the policy reads `name` and `description` from the nested object while still filtering the parent `tools` array. @@ -172,7 +172,7 @@ policies: } ``` -### Scenario 2: Filtering Tools by Threshold +### Scenario 2: Filtering tools by threshold In this scenario, only tools with a semantic similarity score of 0.7 or higher are included. @@ -188,7 +188,7 @@ policies: # Rest of the parameters ``` -### Scenario 3: Text Format (XML-like Tags) +### Scenario 3: Text format (XML-like tags) This scenario handles cases where the user query and tool definitions are embedded in a text payload using custom tags. diff --git a/en/docs/cloud/ai-gateway/llm/guardrails/sentence-count.md b/en/docs/cloud/ai-gateway/llm/guardrails/sentence-count.md index d08ba493..6d8b6ce0 100644 --- a/en/docs/cloud/ai-gateway/llm/guardrails/sentence-count.md +++ b/en/docs/cloud/ai-gateway/llm/guardrails/sentence-count.md @@ -1,4 +1,4 @@ -# Sentence Count Guardrail +# Sentence count guardrail ## Overview @@ -16,7 +16,7 @@ The Sentence Count Guardrail validates the sentence count of request or response ### Parameters -#### Request Phase +#### Request phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -26,7 +26,7 @@ The Sentence Count Guardrail validates the sentence count of request or response | `invert` | boolean | No | `false` | If `true`, validation passes when sentence count is NOT within the min-max range. If `false`, validation passes when sentence count is within the range. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information in error responses. | -#### Response Phase +#### Response phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -36,7 +36,7 @@ The Sentence Count Guardrail validates the sentence count of request or response | `invert` | boolean | No | `false` | If `true`, validation passes when sentence count is NOT within the min-max range. If `false`, validation passes when sentence count is within the range. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information in error responses. | -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and validate specific fields within JSON payloads. Common examples: @@ -47,7 +47,7 @@ The guardrail supports JSONPath expressions to extract and validate specific fie If `jsonPath` is empty or not specified, the entire payload is treated as a string and validated. -## Sentence Detection +## Sentence detection Sentences are detected based on standard sentence-ending punctuation marks: - Period (.) @@ -58,7 +58,7 @@ The guardrail counts sequences of characters ending with these punctuation marks ## Examples -### Example 1: Basic Sentence Count Validation +### Example 1: Basic sentence count validation Deploy an LLM provider that ensures requests contain between 1 and 10 sentences: @@ -141,31 +141,31 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Additional Configuration Options +### Additional configuration options You can customize the guardrail behavior by modifying the `policies` section: -- **Request and Response Validation**: Configure both `request` and `response` parameters to validate sentence counts in both directions. Use `showAssessment: true` to include detailed assessment information in error responses. +- **Request and response validation**: Configure both `request` and `response` parameters to validate sentence counts in both directions. Use `showAssessment: true` to include detailed assessment information in error responses. -- **Inverted Logic**: Set `invert: true` to allow only content *outside* the specified sentence range. This is useful for blocking content that falls within a prohibited sentence count range. +- **Inverted logic**: Set `invert: true` to allow only content *outside* the specified sentence range. This is useful for blocking content that falls within a prohibited sentence count range. -- **Full Payload Validation**: Omit the `jsonPath` parameter to validate the entire request body without JSONPath extraction. +- **Full payload validation**: Omit the `jsonPath` parameter to validate the entire request body without JSONPath extraction. -- **Field-Specific Validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). +- **Field-specific validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). -## Use Cases +## Use cases -1. **Content Quality Assurance**: Ensure responses meet minimum sentence requirements for completeness and clarity. +1. **Content quality assurance**: Ensure responses meet minimum sentence requirements for completeness and clarity. -2. **Response Length Control**: Limit verbosity to maintain concise communication standards. +2. **Response length control**: Limit verbosity to maintain concise communication standards. -3. **Input Validation**: Ensure user prompts contain sufficient context (minimum sentences) without being excessive. +3. **Input validation**: Ensure user prompts contain sufficient context (minimum sentences) without being excessive. -4. **Consistency Enforcement**: Maintain consistent response formats across different AI interactions. +4. **Consistency enforcement**: Maintain consistent response formats across different AI interactions. -5. **Cost Management**: Control response length to manage token usage and associated costs. +5. **Cost management**: Control response length to manage token usage and associated costs. -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: diff --git a/en/docs/cloud/ai-gateway/llm/guardrails/url.md b/en/docs/cloud/ai-gateway/llm/guardrails/url.md index ed53f501..25d41121 100644 --- a/en/docs/cloud/ai-gateway/llm/guardrails/url.md +++ b/en/docs/cloud/ai-gateway/llm/guardrails/url.md @@ -1,4 +1,4 @@ -# URL Guardrail +# URL guardrail ## Overview @@ -16,7 +16,7 @@ The URL Guardrail validates URLs found in request or response body content by ch ### Parameters -#### Request Phase +#### Request phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -25,7 +25,7 @@ The URL Guardrail validates URLs found in request or response body content by ch | `timeout` | integer | No | `3000` | Timeout in milliseconds for DNS lookup or HTTP HEAD request. Default is 3000ms (3 seconds). | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information including invalid URLs in error responses. | -#### Response Phase +#### Response phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -34,7 +34,7 @@ The URL Guardrail validates URLs found in request or response body content by ch | `timeout` | integer | No | `3000` | Timeout in milliseconds for DNS lookup or HTTP HEAD request. Default is 3000ms (3 seconds). | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information including invalid URLs in error responses. | -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and validate specific fields within JSON payloads. Common examples: @@ -45,9 +45,9 @@ The guardrail supports JSONPath expressions to extract and validate specific fie If `jsonPath` is empty or not specified, the entire payload is treated as a string and validated. -## URL Validation Modes +## URL validation modes -### DNS-Only Validation (`onlyDNS: true`) +### DNS-only validation (`onlydns: true`) - Faster validation method - Only checks if the domain name resolves via DNS @@ -55,7 +55,7 @@ If `jsonPath` is empty or not specified, the entire payload is treated as a stri - Less reliable for detecting broken links - Suitable for quick validation when HTTP checks are not necessary -### HTTP HEAD Request Validation (`onlyDNS: false`) +### HTTP HEAD request validation (`onlydns: false`) - More thorough validation method - Performs DNS lookup and HTTP HEAD request @@ -66,7 +66,7 @@ If `jsonPath` is empty or not specified, the entire payload is treated as a stri ## Examples -### Example 1: Basic URL Validation +### Example 1: Basic URL validation Deploy an LLM provider that validates URLs in request content using HTTP HEAD requests: @@ -149,35 +149,35 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Additional Configuration Options +### Additional configuration options You can customize the guardrail behavior by modifying the `policies` section: -- **Request and Response Validation**: Configure both `request` and `response` parameters to validate URLs in both directions. Use `showAssessment: true` to include detailed assessment information including invalid URLs in error responses. +- **Request and response validation**: Configure both `request` and `response` parameters to validate URLs in both directions. Use `showAssessment: true` to include detailed assessment information including invalid URLs in error responses. -- **DNS-Only Validation**: Set `onlyDNS: true` for faster validation that only checks DNS resolution. This is less reliable but faster than HTTP HEAD validation. +- **DNS-only validation**: Set `onlyDNS: true` for faster validation that only checks DNS resolution. This is less reliable but faster than HTTP HEAD validation. -- **HTTP HEAD Validation**: Set `onlyDNS: false` (default) for more thorough validation that performs both DNS lookup and HTTP HEAD request to verify URL reachability. +- **HTTP HEAD validation**: Set `onlyDNS: false` (default) for more thorough validation that performs both DNS lookup and HTTP HEAD request to verify URL reachability. -- **Timeout Configuration**: Adjust the `timeout` parameter (in milliseconds) based on network conditions and acceptable latency. Default is 3000ms (3 seconds). +- **Timeout configuration**: Adjust the `timeout` parameter (in milliseconds) based on network conditions and acceptable latency. Default is 3000ms (3 seconds). -- **Full Payload Validation**: Omit the `jsonPath` parameter to validate URLs in the entire request body without JSONPath extraction. +- **Full payload validation**: Omit the `jsonPath` parameter to validate URLs in the entire request body without JSONPath extraction. -- **Field-Specific Validation**: Use `jsonPath` to extract and validate URLs from specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). +- **Field-specific validation**: Use `jsonPath` to extract and validate URLs from specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). -## Use Cases +## Use cases -1. **Link Validation**: Ensure all URLs in AI-generated content are valid and accessible. +1. **Link validation**: Ensure all URLs in AI-generated content are valid and accessible. 2. **Security**: Detect and block potentially malicious or suspicious URLs. -3. **Quality Assurance**: Prevent broken links from being included in responses. +3. **Quality assurance**: Prevent broken links from being included in responses. -4. **Content Moderation**: Validate URLs before allowing them in user-generated content. +4. **Content moderation**: Validate URLs before allowing them in user-generated content. -5. **Resource Verification**: Ensure referenced resources are available before processing. +5. **Resource verification**: Ensure referenced resources are available before processing. -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: diff --git a/en/docs/cloud/ai-gateway/llm/guardrails/word-count.md b/en/docs/cloud/ai-gateway/llm/guardrails/word-count.md index 064abbd0..00768fe8 100644 --- a/en/docs/cloud/ai-gateway/llm/guardrails/word-count.md +++ b/en/docs/cloud/ai-gateway/llm/guardrails/word-count.md @@ -1,4 +1,4 @@ -# Word Count Guardrail +# Word count guardrail ## Overview @@ -16,7 +16,7 @@ The Word Count Guardrail validates the word count of request or response body co ### Parameters -#### Request Phase +#### Request phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -26,7 +26,7 @@ The Word Count Guardrail validates the word count of request or response body co | `invert` | boolean | No | `false` | If `true`, validation passes when word count is NOT within the min-max range. If `false`, validation passes when word count is within the range. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information in error responses. | -#### Response Phase +#### Response phase | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -36,7 +36,7 @@ The Word Count Guardrail validates the word count of request or response body co | `invert` | boolean | No | `false` | If `true`, validation passes when word count is NOT within the min-max range. If `false`, validation passes when word count is within the range. | | `showAssessment` | boolean | No | `false` | If `true`, includes detailed assessment information in error responses. | -## JSONPath Support +## JSONPath support The guardrail supports JSONPath expressions to extract and validate specific fields within JSON payloads. Common examples: @@ -49,7 +49,7 @@ If `jsonPath` is empty or not specified, the entire payload is treated as a stri ## Examples -### Example 1: Basic Word Count Validation +### Example 1: Basic word count validation Deploy an LLM provider that validates request messages contain between 10 and 500 words: @@ -132,30 +132,30 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Additional Configuration Options +### Additional configuration options You can customize the guardrail behavior by modifying the `policies` section: -- **Request and Response Validation**: Configure both `request` and `response` parameters to validate word counts in both directions. Use `showAssessment: true` to include detailed assessment information in error responses. +- **Request and response validation**: Configure both `request` and `response` parameters to validate word counts in both directions. Use `showAssessment: true` to include detailed assessment information in error responses. -- **Inverted Logic**: Set `invert: true` to allow only content *outside* the specified word range. This is useful for blocking content that falls within a prohibited range. +- **Inverted logic**: Set `invert: true` to allow only content *outside* the specified word range. This is useful for blocking content that falls within a prohibited range. -- **Full Payload Validation**: Omit the `jsonPath` parameter to validate the entire request body without JSONPath extraction. +- **Full payload validation**: Omit the `jsonPath` parameter to validate the entire request body without JSONPath extraction. -- **Field-Specific Validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). +- **Field-specific validation**: Use `jsonPath` to extract and validate specific fields within JSON payloads (e.g., `"$.messages[0].content"` for message content or `"$.choices[0].message.content"` for response content). -## Use Cases +## Use cases -1. **Input Length Control**: Prevent users from submitting extremely long prompts that could impact system performance or costs. +1. **Input length control**: Prevent users from submitting extremely long prompts that could impact system performance or costs. -2. **Response Quality Assurance**: Ensure AI-generated responses meet minimum length requirements for completeness. +2. **Response quality assurance**: Ensure AI-generated responses meet minimum length requirements for completeness. -3. **Cost Management**: Limit response lengths to control token usage and associated costs. +3. **Cost management**: Limit response lengths to control token usage and associated costs. -4. **Content Filtering**: Use inverted logic to block content that falls outside acceptable word count ranges. +4. **Content filtering**: Use inverted logic to block content that falls outside acceptable word count ranges. -## Error Response +## Error response When validation fails, the guardrail returns an HTTP 422 status code with the following structure: diff --git a/en/docs/cloud/ai-gateway/llm/index.md b/en/docs/cloud/ai-gateway/llm/index.md index 0ea0cab9..2079d6a4 100644 --- a/en/docs/cloud/ai-gateway/llm/index.md +++ b/en/docs/cloud/ai-gateway/llm/index.md @@ -2,7 +2,7 @@ The AI Gateway LLM docs cover provider onboarding, application-facing proxies, and policy controls for Large Language Model traffic. -## In This Section +## In this section - [Quick Start Guide](quick-start-guide.md) for deploying the gateway and routing traffic to an LLM provider - [LLM Provider Templates](llm-templates.md) for supported provider metadata extraction and custom template management diff --git a/en/docs/cloud/ai-gateway/llm/llm-templates.md b/en/docs/cloud/ai-gateway/llm/llm-templates.md index a99e536c..0fc330b2 100644 --- a/en/docs/cloud/ai-gateway/llm/llm-templates.md +++ b/en/docs/cloud/ai-gateway/llm/llm-templates.md @@ -1,14 +1,14 @@ -# LLM Provider Templates +# LLM provider templates ## Overview LLM Provider Templates define the characteristics and behaviors specific to an AI service provider, such as OpenAI, Azure OpenAI, Anthropic, or other LLM platforms. These templates describe how the gateway should interpret and extract usage and operational metadata from LLM provider responses, including: -- **Token Usage Metrics**: Prompt tokens, completion tokens, total tokens, and remaining tokens -- **Model Information**: Request and response model identifiers -- **Rate Limiting Data**: Remaining token allowances from response +- **Token usage metrics**: Prompt tokens, completion tokens, total tokens, and remaining tokens +- **Model information**: Request and response model identifiers +- **Rate limiting data**: Remaining token allowances from response -## Out-of-the-Box Supported Templates +## Out-of-the-box supported templates The API Platform Gateway ships with the following pre-configured LLM provider templates that platform administrators can use immediately without any additional configuration: @@ -24,7 +24,7 @@ The API Platform Gateway ships with the following pre-configured LLM provider te These templates are automatically loaded when the gateway starts and are immediately available for use when creating LLM providers. -## Template Structure +## Template structure Each LLM provider template follows a standard YAML structure: @@ -56,7 +56,7 @@ spec: identifier: ``` -### Metadata Extraction Patterns +### Metadata extraction patterns Templates support three types of extraction locations: @@ -64,7 +64,7 @@ Templates support three types of extraction locations: - **`header`**: Extract from HTTP response headers using header name (e.g., `x-ratelimit-remaining-tokens`) - **`pathParam`**: Extract from URL path using regular expressions (e.g., `(?<=models/)[a-zA-Z0-9.\-]+`) -## Template Details +## Template details ### OpenAI @@ -246,7 +246,7 @@ spec: identifier: (?<=model/)[a-zA-Z0-9.:-]+(?=/) ``` -### Azure AI Foundry +### Azure AI foundry The Azure AI Foundry template supports Microsoft's Azure AI Foundry platform. @@ -277,7 +277,7 @@ spec: identifier: $.model ``` -## Creating an LLM Provider with a Template +## Creating an LLM provider with a template To create an LLM provider using any of the out-of-the-box templates: @@ -327,9 +327,9 @@ The gateway automatically uses the template's metadata extraction patterns to: - Enable token-based rate limiting policies - Provide consistent monitoring across different LLM providers -## Managing Templates +## Managing templates -### Listing Available Templates +### Listing available templates To list all available LLM provider templates: @@ -338,7 +338,7 @@ curl -X GET http://localhost:9090/llm-provider-templates \ -H "Authorization: Basic " ``` -### Retrieving a Specific Template +### Retrieving a specific template To retrieve details of a specific template: @@ -347,7 +347,7 @@ curl -X GET http://localhost:9090/llm-provider-templates/openai \ -H "Authorization: Basic " ``` -### Creating Custom Templates +### Creating custom templates Platform administrators can create custom templates for LLM providers not covered by the out-of-the-box templates: @@ -368,7 +368,7 @@ spec: EOF ``` -### Updating Templates +### Updating templates To update an existing custom template: @@ -390,7 +390,7 @@ spec: EOF ``` -### Deleting Custom Templates +### Deleting custom templates To delete a custom template: @@ -401,7 +401,7 @@ curl -X DELETE http://localhost:9090/llm-provider-templates/custom-provider \ **Note**: Out-of-the-box templates cannot be deleted or modified. Only custom templates created by platform administrators can be updated or deleted. -## Template Field Reference +## Template field reference | Field | Type | Required | Description | |-------|------|----------|-------------| @@ -416,7 +416,7 @@ curl -X DELETE http://localhost:9090/llm-provider-templates/custom-provider \ | `spec.requestModel` | object | No | Configuration for extracting request model identifier | | `spec.responseModel` | object | No | Configuration for extracting response model identifier | -### Extraction Configuration Object +### Extraction configuration object Each extraction configuration object has the following structure: diff --git a/en/docs/cloud/ai-gateway/llm/load-balancing/model-round-robin.md b/en/docs/cloud/ai-gateway/llm/load-balancing/model-round-robin.md index ca0da8ae..4ac5f389 100644 --- a/en/docs/cloud/ai-gateway/llm/load-balancing/model-round-robin.md +++ b/en/docs/cloud/ai-gateway/llm/load-balancing/model-round-robin.md @@ -1,4 +1,4 @@ -# Model Round Robin +# Model round robin ## Overview @@ -21,7 +21,7 @@ The Model Round Robin policy implements round-robin load balancing for AI models | `models` | array | Yes | - | List of models for round-robin distribution. Each model must have a `model` name. | | `suspendDuration` | integer | No | `0` | Suspend duration in seconds for failed models. If set to 0, failed model knowledge is not persisted. Must be >= 0. | -### Model Configuration +### Model configuration Each model in the `models` array is an object with the following properties: @@ -38,17 +38,17 @@ The policy requires `requestModel` configuration from the LLM provider template | `requestModel.location` | string | Yes | Location of the model identifier: `payload`, `header`, `queryParam`, or `pathParam` | | `requestModel.identifier` | string | Yes | JSONPath (for payload), header name (for header), query param name (for queryParam), or regex pattern (for pathParam) to extract model | -## How It Works +## How it works -1. **Model Selection**: On each request, the policy selects the next available model in the configured list using a round-robin algorithm. -2. **Model Extraction**: The policy extracts the original model from the request (if configured) and stores it for reference. -3. **Model Modification**: The policy modifies the request to use the selected model based on the `requestModel` configuration. -4. **Failure Handling**: If a model returns a 5xx or 429 response, and `suspendDuration` is configured, the model is suspended for the specified duration. -5. **Availability Check**: Suspended models are skipped during selection until their suspension period expires. +1. **Model selection**: On each request, the policy selects the next available model in the configured list using a round-robin algorithm. +2. **Model extraction**: The policy extracts the original model from the request (if configured) and stores it for reference. +3. **Model modification**: The policy modifies the request to use the selected model based on the `requestModel` configuration. +4. **Failure handling**: If a model returns a 5xx or 429 response, and `suspendDuration` is configured, the model is suspended for the specified duration. +5. **Availability check**: Suspended models are skipped during selection until their suspension period expires. ## Examples -### Example 1: Basic Round Robin with Payload-based Model +### Example 1: Basic round robin with payload-based model Deploy an LLM provider with round-robin load balancing across multiple models: @@ -142,37 +142,37 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -## Model Suspension +## Model suspension When a model returns a 5xx or 429 response, the policy can automatically suspend that model for a configurable duration: -- **Suspension Duration**: Configured via the `suspendDuration` parameter (in seconds) -- **Automatic Recovery**: Suspended models are automatically re-enabled after the suspension period expires -- **Availability Check**: Suspended models are skipped during round-robin selection until they recover +- **Suspension duration**: Configured via the `suspendDuration` parameter (in seconds) +- **Automatic recovery**: Suspended models are automatically re-enabled after the suspension period expires +- **Availability check**: Suspended models are skipped during round-robin selection until they recover -### Suspension Behavior +### Suspension behavior - Suspension is tracked per model across all requests - If all models are suspended, the policy returns HTTP 503 with error: "All models are currently unavailable" - Suspension period starts from the time of failure -## Use Cases +## Use cases -1. **Load Distribution**: Distribute requests evenly across multiple models to prevent overloading any single model. +1. **Load distribution**: Distribute requests evenly across multiple models to prevent overloading any single model. -2. **High Availability**: Automatically route requests to available models when some models are experiencing issues. +2. **High availability**: Automatically route requests to available models when some models are experiencing issues. -3. **Cost Optimization**: Distribute requests across different model tiers (e.g., expensive and cheaper models) to balance cost and performance. +3. **Cost optimization**: Distribute requests across different model tiers (e.g., expensive and cheaper models) to balance cost and performance. -4. **A/B Testing**: Test different models with equal traffic distribution to compare performance and quality. +4. **A/B testing**: Test different models with equal traffic distribution to compare performance and quality. -5. **Multi-Provider Support**: Distribute requests across models from different providers while maintaining equal distribution. +5. **Multi-provider support**: Distribute requests across models from different providers while maintaining equal distribution. -## Request Model Locations +## Request model locations The policy supports extracting the model identifier from different locations in the request: -### Payload (JSONPath) +### Payload (jsonpath) Extract model from JSON payload using JSONPath: @@ -186,14 +186,14 @@ Extract model from HTTP header: - **Location**: `header` - **Identifier**: Header name (e.g., `X-Model-Name`, `X-LLM-Model`) -### Query Parameter +### Query parameter Extract model from URL query parameter: - **Location**: `queryParam` - **Identifier**: Query parameter name (e.g., `model`, `llm_model`) -### Path Parameter +### Path parameter Extract model from URL path using regex: diff --git a/en/docs/cloud/ai-gateway/llm/load-balancing/model-weighted-round-robin.md b/en/docs/cloud/ai-gateway/llm/load-balancing/model-weighted-round-robin.md index 2c0f5119..e4648d60 100644 --- a/en/docs/cloud/ai-gateway/llm/load-balancing/model-weighted-round-robin.md +++ b/en/docs/cloud/ai-gateway/llm/load-balancing/model-weighted-round-robin.md @@ -1,4 +1,4 @@ -# Model Weighted Round Robin +# Model weighted round robin ## Overview @@ -22,7 +22,7 @@ The Model Weighted Round Robin policy implements weighted round-robin load balan | `models` | array | Yes | - | List of models with weights for weighted round-robin distribution. Each model must have a `model` name and `weight`. | | `suspendDuration` | integer | No | `0` | Suspend duration in seconds for failed models. If set to 0, failed model knowledge is not persisted. Must be >= 0. | -### Model Configuration +### Model configuration Each model in the `models` array is an object with the following properties: @@ -40,16 +40,16 @@ The policy requires `requestModel` configuration from the LLM provider template | `requestModel.location` | string | Yes | Location of the model identifier: `payload`, `header`, `queryParam`, or `pathParam` | | `requestModel.identifier` | string | Yes | JSONPath (for payload), header name (for header), query param name (for queryParam), or regex pattern (for pathParam) to extract model | -## How It Works +## How it works -1. **Weight Calculation**: During policy initialization, the policy calculates the total weight of all configured models and builds a weighted sequence where each model appears a number of times proportional to its weight. This sequence is built once and reused for all requests. -2. **Model Selection**: On each request, the policy selects the next available model from the pre-computed weighted sequence using a round-robin algorithm. -3. **Model Extraction**: The policy extracts the original model from the request using the `requestModel` configuration and stores it for reference. -4. **Model Modification**: The policy modifies the request to use the selected model based on the `requestModel` configuration. -5. **Failure Handling**: If a model returns a 5xx or 429 response, and `suspendDuration` is configured, the model is suspended for the specified duration. -6. **Availability Check**: Suspended models are skipped during selection until their suspension period expires. +1. **Weight calculation**: During policy initialization, the policy calculates the total weight of all configured models and builds a weighted sequence where each model appears a number of times proportional to its weight. This sequence is built once and reused for all requests. +2. **Model selection**: On each request, the policy selects the next available model from the pre-computed weighted sequence using a round-robin algorithm. +3. **Model extraction**: The policy extracts the original model from the request using the `requestModel` configuration and stores it for reference. +4. **Model modification**: The policy modifies the request to use the selected model based on the `requestModel` configuration. +5. **Failure handling**: If a model returns a 5xx or 429 response, and `suspendDuration` is configured, the model is suspended for the specified duration. +6. **Availability check**: Suspended models are skipped during selection until their suspension period expires. -### Weight Distribution Example +### Weight distribution example If you configure three models with weights: - Model A: weight 3 @@ -63,7 +63,7 @@ The weighted sequence would be: `[A, A, A, B, B, C]`, meaning: ## Examples -### Example 1: Basic Weighted Round Robin with Payload-based Model +### Example 1: Basic weighted round robin with payload-based model Deploy an LLM provider with weighted round-robin load balancing: @@ -132,40 +132,40 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -## Model Suspension +## Model suspension When a model returns a 5xx or 429 response, the policy can automatically suspend that model for a configurable duration: -- **Suspension Duration**: Configured via the `suspendDuration` parameter (in seconds) -- **Automatic Recovery**: Suspended models are automatically re-enabled after the suspension period expires -- **Availability Check**: Suspended models are skipped during weighted round-robin selection until they recover -- **Weight Preservation**: When a model is suspended, the remaining models continue to be selected based on their relative weights +- **Suspension duration**: Configured via the `suspendDuration` parameter (in seconds) +- **Automatic recovery**: Suspended models are automatically re-enabled after the suspension period expires +- **Availability check**: Suspended models are skipped during weighted round-robin selection until they recover +- **Weight preservation**: When a model is suspended, the remaining models continue to be selected based on their relative weights -### Suspension Behavior +### Suspension behavior - If all models are suspended, the policy returns HTTP 503 with error: "All models are currently unavailable" - Suspension period starts from the time of failure - When a model is suspended, its entries in the pre-computed weighted sequence are skipped during traversal until the suspension period expires -## Use Cases +## Use cases -1. **Capacity-Based Distribution**: Distribute requests based on model capacity, giving higher weights to models that can handle more load. +1. **Capacity-based distribution**: Distribute requests based on model capacity, giving higher weights to models that can handle more load. -2. **Cost Optimization**: Route more requests to cheaper models while maintaining some traffic to premium models for quality assurance. +2. **Cost optimization**: Route more requests to cheaper models while maintaining some traffic to premium models for quality assurance. -3. **Performance Tiers**: Prioritize high-performance models for critical requests while using standard models for regular traffic. +3. **Performance tiers**: Prioritize high-performance models for critical requests while using standard models for regular traffic. -4. **Gradual Migration**: Gradually shift traffic from old models to new models by adjusting weights over time. +4. **Gradual migration**: Gradually shift traffic from old models to new models by adjusting weights over time. -5. **Multi-Provider Balancing**: Distribute requests across models from different providers with different weights based on SLA or cost agreements. +5. **Multi-provider balancing**: Distribute requests across models from different providers with different weights based on SLA or cost agreements. -6. **A/B Testing with Bias**: Test different models with weighted traffic distribution to compare performance while maintaining a bias toward preferred models. +6. **A/B testing with bias**: Test different models with weighted traffic distribution to compare performance while maintaining a bias toward preferred models. -## Request Model Locations +## Request model locations The policy supports extracting the model identifier from different locations in the request: -### Payload (JSONPath) +### Payload (jsonpath) Extract model from JSON payload using JSONPath: @@ -179,14 +179,14 @@ Extract model from HTTP header: - **Location**: `header` - **Identifier**: Header name (e.g., `X-Model-Name`, `X-LLM-Model`) -### Query Parameter +### Query parameter Extract model from URL query parameter: - **Location**: `queryParam` - **Identifier**: Query parameter name (e.g., `model`, `llm_model`) -### Path Parameter +### Path parameter Extract model from URL path using regex: @@ -195,16 +195,16 @@ Extract model from URL path using regex: **Note**: For path parameters, the regex pattern should include a capturing group to extract the model name. The policy uses the first capturing group as the model identifier. -## Weight Calculation +## Weight calculation The policy builds a weighted sequence by repeating each model a number of times equal to its weight: -- **Total Weight**: Sum of all model weights -- **Sequence Length**: Equal to the total weight +- **Total weight**: Sum of all model weights +- **Sequence length**: Equal to the total weight - **Distribution**: Each model appears in the sequence `weight` times -- **Proportional Selection**: Over time, each model receives requests proportional to `model_weight / total_weight` +- **Proportional selection**: Over time, each model receives requests proportional to `model_weight / total_weight` -### Example Weight Distribution +### Example weight distribution For models with weights [5, 3, 2]: - Total weight: 10 diff --git a/en/docs/cloud/ai-gateway/llm/prompt-management/prompt-decorator.md b/en/docs/cloud/ai-gateway/llm/prompt-management/prompt-decorator.md index bc4f740a..25b7ed3d 100644 --- a/en/docs/cloud/ai-gateway/llm/prompt-management/prompt-decorator.md +++ b/en/docs/cloud/ai-gateway/llm/prompt-management/prompt-decorator.md @@ -1,4 +1,4 @@ -# Prompt Decorator +# Prompt decorator ## Overview @@ -22,15 +22,15 @@ The Prompt Decorator policy dynamically modifies prompts by prepending or append | `jsonPath` | string | Yes | - | JSONPath expression to locate the field to decorate. Use `$.messages[0].content` for text decoration, or `$.messages` for chat decoration. | | `append` | boolean | No | `false` | If `true`, decoration is appended to the content. If `false`, decoration is prepended (default). | -## Decoration Modes +## Decoration modes -### Mode 1: Text Prompt Decoration +### Mode 1: Text prompt decoration Text decoration is used when the JSONPath targets a string field (e.g., `$.messages[0].content`). The decoration can be: - A simple string that gets prepended or appended to the content - An array of decoration objects (their content fields are concatenated with newlines) -**Configuration Example:** +**Configuration example:** ```json { "decoration": "Summarize the following content in a concise, neutral, and professional tone. Structure the summary using bullet points if appropriate.\n\n" @@ -41,11 +41,11 @@ Text decoration is used when the JSONPath targets a string field (e.g., `$.messa - Decoration string is prepended or appended to the target content field - A space is automatically added between the decoration and original content -### Mode 2: Chat Prompt Decoration +### Mode 2: Chat prompt decoration Chat decoration is used when the JSONPath targets an array field (e.g., `$.messages`). The decoration must be an array of message objects: -**Configuration Example:** +**Configuration example:** ```json { "decoration": [ @@ -62,7 +62,7 @@ Chat decoration is used when the JSONPath targets an array field (e.g., `$.messa - Each decoration object must have `role` and `content` fields - Multiple decoration messages can be added -## JSONPath Support +## JSONPath support The decorator supports JSONPath expressions to target specific fields. Common examples: @@ -71,13 +71,13 @@ The decorator supports JSONPath expressions to target specific fields. Common ex - `$.messages` - Entire messages array (chat decoration) - `$.data.text` - Nested text field (text decoration) -**Array Index Syntax:** +**Array index syntax:** - Use `[0]` for first element, `[1]` for second, etc. - Use `[-1]` for last element, `[-2]` for second-to-last, etc. ## Examples -### Example 1: Text Prompt Decoration - Summarization Directive +### Example 1: Text prompt decoration - summarization directive Add a summarization instruction to user prompts: @@ -152,7 +152,7 @@ curl -X POST http://openai:8080/chat/completions \ # } ``` -### Example 2: Chat Prompt Decoration - System Persona +### Example 2: Chat prompt decoration - system persona Add a system message to define AI behavior: @@ -227,7 +227,7 @@ curl -X POST http://openai:8080/chat/completions \ # } ``` -### Example 3: Append Mode - Adding Suffix Instructions +### Example 3: Append mode - adding suffix instructions Append instructions to the end of user messages: @@ -244,25 +244,25 @@ policies: append: true ``` -## Use Cases +## Use cases -1. **Consistent Instructions**: Prepend standardized instructions or guidelines to all prompts to ensure consistent AI behavior. +1. **Consistent instructions**: Prepend standardized instructions or guidelines to all prompts to ensure consistent AI behavior. -2. **System Personas**: Inject system messages to define AI personality, role, or behavior before user interactions. +2. **System personas**: Inject system messages to define AI personality, role, or behavior before user interactions. -3. **Quality Enhancement**: Add formatting instructions (e.g., "respond in bullet points", "use professional tone") to improve response quality. +3. **Quality enhancement**: Add formatting instructions (e.g., "respond in bullet points", "use professional tone") to improve response quality. -4. **Context Addition**: Prepend contextual information or background details to enrich prompts. +4. **Context addition**: Prepend contextual information or background details to enrich prompts. -5. **Multi-turn Conversations**: Add system messages at the beginning of chat conversations to set conversation rules. +5. **Multi-turn conversations**: Add system messages at the beginning of chat conversations to set conversation rules. 6. **Compliance**: Append compliance-related instructions or disclaimers to prompts. -7. **Output Formatting**: Add instructions for specific output formats (JSON, markdown, structured text) to prompts. +7. **Output formatting**: Add instructions for specific output formats (JSON, markdown, structured text) to prompts. -## Configuration Reference +## Configuration reference -### Text Decoration Configuration +### Text decoration configuration ```json { @@ -273,7 +273,7 @@ policies: - Simple string that will be prepended or appended to the target content - A space is automatically added between decoration and original content -### Chat Decoration Configuration +### Chat decoration configuration ```json { @@ -290,7 +290,7 @@ policies: - Each object must have `role` (e.g., "system", "user", "assistant") and `content` fields - Messages are prepended or appended to the messages array in the order specified -## Error Response +## Error response When the policy encounters an error (e.g., invalid JSONPath, missing fields), it returns an HTTP 500 status code with the following structure: diff --git a/en/docs/cloud/ai-gateway/llm/prompt-management/prompt-template.md b/en/docs/cloud/ai-gateway/llm/prompt-management/prompt-template.md index af0cafbe..4f914d71 100644 --- a/en/docs/cloud/ai-gateway/llm/prompt-management/prompt-template.md +++ b/en/docs/cloud/ai-gateway/llm/prompt-management/prompt-template.md @@ -1,4 +1,4 @@ -# Prompt Template +# Prompt template ## Overview @@ -20,7 +20,7 @@ The Prompt Template policy enables dynamic prompt transformation by replacing `t |-----------|------|----------|---------|-------------| | `promptTemplateConfig` | string | Yes | - | JSON string containing an array of template objects. Each template must have a `name` and `prompt` field. Example: `[{"name": "translate", "prompt": "Translate from [[from]] to [[to]]: [[text]]"}]` | -### Template Configuration Format +### Template configuration format The `promptTemplateConfig` must be a JSON array of template objects: @@ -37,9 +37,9 @@ Each template object contains: - **name**: Unique identifier for the template (used in `template://` URIs) - **prompt**: The template string with `[[parameter-name]]` placeholders that will be replaced -## Template Syntax +## Template syntax -### Template URI Format +### Template URI format Templates are referenced in JSON payloads using the following URI format: @@ -52,7 +52,7 @@ Example: template://translate?from=english&to=spanish&text=Hello world ``` -### Placeholder Syntax +### Placeholder syntax Within template prompts, use double square brackets to define placeholders: @@ -74,7 +74,7 @@ Translate the following text from english to spanish: Hello ## Examples -### Example 1: Translation Template +### Example 1: Translation template Deploy an LLM provider with a translation prompt template: @@ -149,7 +149,7 @@ The policy will transform the request to: } ``` -### Example 2: Summarization Template +### Example 2: Summarization template Create a template for summarizing content with configurable length: @@ -206,7 +206,7 @@ curl -X POST http://openai:8080/chat/completions \ }' ``` -### Example 3: Multiple Templates +### Example 3: Multiple templates Configure multiple templates in a single policy: @@ -235,19 +235,19 @@ policies: ] ``` -## Use Cases +## Use cases -1. **Standardized Prompts**: Ensure consistent prompt formatting across different API consumers by centralizing prompt definitions. +1. **Standardized prompts**: Ensure consistent prompt formatting across different API consumers by centralizing prompt definitions. -2. **Reusable Templates**: Create library of common prompts (translation, summarization, explanation) that can be reused across multiple APIs. +2. **Reusable templates**: Create library of common prompts (translation, summarization, explanation) that can be reused across multiple APIs. -3. **Parameterized Prompts**: Allow dynamic content insertion while maintaining consistent prompt structure and quality. +3. **Parameterized prompts**: Allow dynamic content insertion while maintaining consistent prompt structure and quality. -4. **Multi-language Support**: Use templates with language parameters to standardize prompts for different locales. +4. **Multi-language support**: Use templates with language parameters to standardize prompts for different locales. -5. **Prompt Versioning**: Update prompt templates centrally without requiring changes to client applications. +5. **Prompt versioning**: Update prompt templates centrally without requiring changes to client applications. -## Template Pattern Matching +## Template pattern matching The policy uses regex pattern matching to find `template://` URIs in the JSON payload: @@ -255,14 +255,14 @@ The policy uses regex pattern matching to find `template://` URIs in the JSON pa - **Location**: Searches the entire JSON payload as a string - **Replacement**: Each matched pattern is replaced with the resolved template string (JSON-escaped) -### Pattern Details +### Pattern details - Template names can contain letters, numbers, underscores, and hyphens - Query parameters can contain any characters except spaces, quotes, or single quotes - Multiple template:// patterns can exist in a single payload - Each pattern is resolved independently -## Error Handling +## Error handling If a template:// pattern references a template name that doesn't exist in the configuration, the pattern is left unchanged (no replacement occurs). This allows for graceful handling of missing templates. diff --git a/en/docs/cloud/ai-gateway/llm/quick-start-guide.md b/en/docs/cloud/ai-gateway/llm/quick-start-guide.md index 47a6dadf..06e3320f 100644 --- a/en/docs/cloud/ai-gateway/llm/quick-start-guide.md +++ b/en/docs/cloud/ai-gateway/llm/quick-start-guide.md @@ -1,6 +1,6 @@ -## Quick Start +## Quick start -### Using Docker Compose (Recommended) +### Using Docker compose (recommended) ### Prerequisites @@ -129,7 +129,7 @@ curl -X POST "https://localhost:8443/assistant/chat/completions" \ }' -k ``` -## Stopping the Gateway +## Stopping the gateway When stopping the gateway, you have two options: diff --git a/en/docs/cloud/ai-gateway/llm/semantic-caching.md b/en/docs/cloud/ai-gateway/llm/semantic-caching.md index 7795201c..ed86c3ad 100644 --- a/en/docs/cloud/ai-gateway/llm/semantic-caching.md +++ b/en/docs/cloud/ai-gateway/llm/semantic-caching.md @@ -1,4 +1,4 @@ -# Semantic Caching +# Semantic caching ## Overview @@ -17,37 +17,37 @@ The policy uses embedding models to convert request text into high-dimensional v - **Immediate response on cache hit**: Returns cached response with `X-Cache-Status: HIT` header without upstream call - **TTL support**: Configurable time-to-live for cache entries -## How It Works +## How it works -### Request Phase +### Request phase -1. **Text Extraction**: Extracts text from the request body using JSONPath (if configured) or uses the entire request body -2. **Embedding Generation**: Generates a vector embedding from the extracted text using the configured embedding provider -3. **Cache Lookup**: Searches the vector database for semantically similar cached responses using cosine similarity -4. **Threshold Check**: If a similar embedding is found with similarity >= similarityThreshold, returns the cached response immediately -5. **Cache Miss**: If no similar response is found, the request proceeds to the upstream service +1. **Text extraction**: Extracts text from the request body using JSONPath (if configured) or uses the entire request body +2. **Embedding generation**: Generates a vector embedding from the extracted text using the configured embedding provider +3. **Cache lookup**: Searches the vector database for semantically similar cached responses using cosine similarity +4. **Threshold check**: If a similar embedding is found with similarity >= similarityThreshold, returns the cached response immediately +5. **Cache miss**: If no similar response is found, the request proceeds to the upstream service -### Response Phase +### Response phase -1. **Success Check**: Only processes responses with 200 status codes -2. **Embedding Retrieval**: Retrieves the embedding generated during the request phase from metadata -3. **Response Storage**: Stores the response payload along with its embedding in the vector database +1. **Success check**: Only processes responses with 200 status codes +2. **Embedding retrieval**: Retrieves the embedding generated during the request phase from metadata +3. **Response storage**: Stores the response payload along with its embedding in the vector database 4. **TTL Application**: Applies the configured TTL to the cache entry ## Configuration -### Policy Parameters +### Policy parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `similarityThreshold` | number | Yes | - | Similarity threshold for cache hits (0.0 to 1.0). Higher values require more similarity. For example, 0.9 means 90% similarity required. Recommended: 0.85-0.95 for strict matching, 0.70-0.85 for more flexible matching. | | `jsonPath` | string | No | `""` | JSONPath expression to extract text from request body for embedding generation. If empty, uses the entire request body. Example: `"$.messages[0].content"` to extract the first message's content. | -### System Parameters (Required) +### System parameters (required) These parameters are typically configured at the gateway level and automatically injected, or you can override those values from the params section in the api artifact definition file as well: -#### Embedding Provider Configuration +#### Embedding provider configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| @@ -57,7 +57,7 @@ These parameters are typically configured at the gateway level and automatically | `embeddingDimension` | integer | Yes | Dimension of embedding vectors. Common values: 1536 (OpenAI ada-002), 1024 (Mistral). Must match the model's output dimension. | | `apiKey` | string | Yes | API key for the embedding service authentication. The authentication header is automatically set to `api-key` for Azure OpenAI and `Authorization` for other providers. | -#### Vector Database Configuration +#### Vector database configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| @@ -70,7 +70,7 @@ These parameters are typically configured at the gateway level and automatically | `ttl` | integer | No | Time-to-live for cache entries in seconds. Default is 3600 (1 hour). Set to 0 for no expiration. | -### Configuring System Parameters in config.toml +### Configuring system parameters in config.toml System parameters can be configured globally in the gateway's `config.toml` file. These values serve as defaults for all Semantic Cache policy instances and can be overridden per-policy in the API configuration if needed. @@ -94,14 +94,14 @@ vector_db_provider_password = "default" vector_db_provider_ttl = 3600 ``` -## JSONPath Support +## JSONPath support The policy supports JSONPath expressions to extract specific text from request bodies before generating embeddings. This is useful for: - Extracting message content from chat completion requests - Focusing on specific prompt fields while ignoring metadata - Handling structured JSON payloads -### Common JSONPath Examples +### Common jsonpath examples - `$.messages[0].content` - First message's content in chat completions - `$.messages[-1].content` - Last message's content @@ -111,7 +111,7 @@ The policy supports JSONPath expressions to extract specific text from request b ## Examples -### Example 1: OpenAI Embeddings with Redis +### Example 1: OpenAI embeddings with Redis Deploy an LLM provider with semantic caching using OpenAI embeddings and Redis vector store: @@ -189,17 +189,17 @@ curl -X POST http://openai:8080/chat/completions \ # Response will include: X-Cache-Status: HIT ``` -## Use Cases +## Use cases -1. **Cost Reduction**: Reduce API costs by serving cached responses for similar queries, especially valuable for expensive LLM API calls. +1. **Cost reduction**: Reduce API costs by serving cached responses for similar queries, especially valuable for expensive LLM API calls. -2. **Latency Improvement**: Return cached responses in milliseconds instead of waiting for LLM processing (typically 1-5 seconds), significantly improving user experience. +2. **Latency improvement**: Return cached responses in milliseconds instead of waiting for LLM processing (typically 1-5 seconds), significantly improving user experience. -3. **Rate Limit Management**: Reduce the number of upstream API calls, helping stay within rate limits and avoiding throttling. +3. **Rate limit management**: Reduce the number of upstream API calls, helping stay within rate limits and avoiding throttling. 4. **Consistency**: Ensure users receive consistent responses for semantically equivalent queries, improving predictability. -5. **Offline Resilience**: Serve cached responses even when upstream services experience temporary outages. +5. **Offline resilience**: Serve cached responses even when upstream services experience temporary outages. 6. **A/B Testing**: Compare cached vs. fresh responses to evaluate prompt engineering improvements. @@ -207,7 +207,7 @@ curl -X POST http://openai:8080/chat/completions \ 8. **High-Traffic Applications**: Handle high volumes of similar queries efficiently without overwhelming upstream services. -## Similarity Threshold Guidelines +## Similarity threshold guidelines The `similarityThreshold` parameter controls how similar requests must be to trigger a cache hit: @@ -219,9 +219,9 @@ The `similarityThreshold` parameter controls how similar requests must be to tri **Recommendation**: Start with 0.85 and adjust based on your use case. Monitor cache hit rates and response relevance to fine-tune. -## Cache Behavior +## Cache behavior -### Cache Hit +### Cache hit When a similar request is found: - Returns cached response immediately (no upstream call) @@ -229,44 +229,44 @@ When a similar request is found: - Status code: 200 (from cached response) - Response time: Typically < 50ms (vs. 1-5 seconds for LLM APIs) -### Cache Miss +### Cache miss When no similar request is found: - Request proceeds to upstream service normally - Response is cached after successful upstream call (200 status) - Subsequent similar requests may hit the cache -### Cache Storage +### Cache storage - Only successful responses (200 status code) are cached - Responses are stored with their embeddings in the vector database - TTL is applied to all cache entries - Each route/API maintains a separate cache namespace to avoid cross-contamination -## Error Handling +## Error handling The policy is designed to be resilient: -- **Embedding Generation Failure**: If embedding generation fails, the request proceeds to upstream (cache is skipped) -- **Vector Database Unavailable**: If the vector database is unreachable, requests proceed to upstream -- **Cache Storage Failure**: If storing a response fails, the response is still returned to the client (cache operation is non-blocking) +- **Embedding generation failure**: If embedding generation fails, the request proceeds to upstream (cache is skipped) +- **Vector database unavailable**: If the vector database is unreachable, requests proceed to upstream +- **Cache storage failure**: If storing a response fails, the response is still returned to the client (cache operation is non-blocking) - **Invalid JSONPath**: If JSONPath extraction fails, the entire request body is used for embedding generation These behaviors ensure that caching failures do not block legitimate requests. The system gracefully degrades to direct upstream calls when caching is unavailable. -## Performance Considerations +## Performance considerations -1. **Embedding Generation Latency**: Generating embeddings adds ~100-500ms to request processing. This is offset by cache hits that save 1-5 seconds. +1. **Embedding generation latency**: Generating embeddings adds ~100-500ms to request processing. This is offset by cache hits that save 1-5 seconds. -2. **Vector Database Performance**: +2. **Vector database performance**: - Redis with RedisSearch: Fast queries, good for smaller datasets (< 1M vectors) - Milvus: Optimized for large-scale vector search, better for > 1M vectors -3. **Cache Hit Rate**: Aim for 20-40% cache hit rate for cost-effective caching. Below 10% may not justify the overhead. +3. **Cache hit rate**: Aim for 20-40% cache hit rate for cost-effective caching. Below 10% may not justify the overhead. -4. **Embedding Dimension**: Higher dimensions (e.g., 1536) provide better accuracy but increase storage and search time. Choose based on your quality requirements. +4. **Embedding dimension**: Higher dimensions (e.g., 1536) provide better accuracy but increase storage and search time. Choose based on your quality requirements. -5. **Index Creation**: Vector database indexes are created automatically on first use. This may take a few seconds for large datasets. +5. **Index creation**: Vector database indexes are created automatically on first use. This may take a few seconds for large datasets. ## Notes diff --git a/en/docs/cloud/ai-gateway/mcp/index.md b/en/docs/cloud/ai-gateway/mcp/index.md index 76986c84..67a10508 100644 --- a/en/docs/cloud/ai-gateway/mcp/index.md +++ b/en/docs/cloud/ai-gateway/mcp/index.md @@ -2,7 +2,7 @@ The AI Gateway MCP docs cover exposing Model Context Protocol servers through the gateway and applying MCP-specific traffic policies. -## In This Section +## In this section - [Quick Start Guide](quick-start-guide.md) for deploying the gateway and publishing an MCP proxy - [MCP Authentication](policies/mcp-authentication.md) for protecting MCP traffic diff --git a/en/docs/cloud/ai-gateway/mcp/policies/mcp-acl-list.md b/en/docs/cloud/ai-gateway/mcp/policies/mcp-acl-list.md index 9f71f5c5..3da27744 100644 --- a/en/docs/cloud/ai-gateway/mcp/policies/mcp-acl-list.md +++ b/en/docs/cloud/ai-gateway/mcp/policies/mcp-acl-list.md @@ -1,7 +1,7 @@ --- title: "Overview" --- -# MCP Access Control List +# MCP access control list ## Overview @@ -11,18 +11,18 @@ The policy operates on three types of MCP capabilities: tools, resources, and pr ## Features -- **Tool-Level Access Control**: Allow or deny access to specific tools using allow/deny mode with exceptions. -- **Resource-Level Access Control**: Control access to specific resources (identified by URI) using flexible ACL rules. -- **Prompt-Level Access Control**: Manage access to specific prompts using configurable access modes. -- **Flexible ACL Modes**: Support both allow-with-exceptions and deny-with-exceptions patterns. -- **List Filtering**: Filter list responses to only include capabilities that match the access control rules. -- **Request Path Enforcement**: Enforce the same allow/deny rules on request paths, rejecting access to denied capabilities. +- **Tool-level access control**: Allow or deny access to specific tools using allow/deny mode with exceptions. +- **Resource-level access control**: Control access to specific resources (identified by URI) using flexible ACL rules. +- **Prompt-level access control**: Manage access to specific prompts using configurable access modes. +- **Flexible ACL modes**: Support both allow-with-exceptions and deny-with-exceptions patterns. +- **List filtering**: Filter list responses to only include capabilities that match the access control rules. +- **Request path enforcement**: Enforce the same allow/deny rules on request paths, rejecting access to denied capabilities. ## Configuration The MCP ACL List policy uses a single-level configuration model where all parameters are configured per-MCP-API/route in the API definition YAML. -### User Parameters (API Definition) +### User parameters (API definition) These parameters are configured per MCP Proxy by the API developer: @@ -34,7 +34,7 @@ These parameters are configured per MCP Proxy by the API developer: > **Note**: At least one of `tools`, `resources`, or `prompts` must be specified. -### ToolACLConfig Configuration +### ToolACLConfig configuration Each `ToolACLConfig` object supports the following fields: @@ -43,7 +43,7 @@ Each `ToolACLConfig` object supports the following fields: | `mode` | string | No | `"deny"` | ACL mode for tools: `allow` (allow all except listed exceptions) or `deny` (deny all except listed exceptions). | | `exceptions` | string array | No | - | List of tool names that are exceptions to the selected mode. Tool names must be 1-256 characters. | -### ResourceACLConfig Configuration +### ResourceACLConfig configuration Each `ResourceACLConfig` object supports the following fields: @@ -52,7 +52,7 @@ Each `ResourceACLConfig` object supports the following fields: | `mode` | string | No | `"deny"` | ACL mode for resources: `allow` (allow all except listed exceptions) or `deny` (deny all except listed exceptions). | | `exceptions` | string array | No | - | List of resource URIs that are exceptions to the selected mode. Resource URIs must be 1-2048 characters. | -### PromptACLConfig Configuration +### PromptACLConfig configuration Each `PromptACLConfig` object supports the following fields: @@ -78,9 +78,9 @@ Inside the `gateway/build.yaml`, ensure the policy module is added under `polici gomodule: github.com/wso2/gateway-controllers/policies/mcp-acl-list@v0 ``` -## Reference Scenarios +## Reference scenarios -### Example 1: Deny Specific Tools +### Example 1: Deny specific tools Deny access to certain tools while allowing all others: @@ -108,7 +108,7 @@ spec: ... ``` -### Example 2: Allow Only Specific Resources +### Example 2: Allow only specific resources Allow access to only whitelisted resources: @@ -136,7 +136,7 @@ spec: ... ``` -### Example 3: Mixed Access Control +### Example 3: Mixed access control Apply different access control rules to different capability types: diff --git a/en/docs/cloud/ai-gateway/mcp/policies/mcp-authentication.md b/en/docs/cloud/ai-gateway/mcp/policies/mcp-authentication.md index 0220a261..e9c7fcc8 100644 --- a/en/docs/cloud/ai-gateway/mcp/policies/mcp-authentication.md +++ b/en/docs/cloud/ai-gateway/mcp/policies/mcp-authentication.md @@ -1,7 +1,7 @@ --- title: "Overview" --- -# MCP Authentication +# MCP authentication ## Overview @@ -9,9 +9,9 @@ The MCP Authentication policy is designed to secure traffic to Model Context Pro ## Features -- **Access Token Validation**: Validates JWT access tokens using configured key managers. Please refer to the [JWT Authentication Policy](https://wso2.com/api-platform/policy-hub/policies/jwt-auth) for more information on how the key validation works. -- **Resource-Specific Security**: Configure authentication independently for tools, resources, prompts, and JSON-RPC methods. -- **Exception Lists**: Exclude specific resources from authentication using exception lists. +- **Access token validation**: Validates JWT access tokens using configured key managers. Please refer to the [JWT Authentication Policy](https://wso2.com/api-platform/policy-hub/policies/jwt-auth) for more information on how the key validation works. +- **Resource-specific security**: Configure authentication independently for tools, resources, prompts, and JSON-RPC methods. +- **Exception lists**: Exclude specific resources from authentication using exception lists. - **Protected Resource Metadata**: Intercepts `GET /.well-known/oauth-protected-resource` requests to return resource metadata, including authorization servers and supported scopes. - **Standardized Error Handling**: Returns `WWW-Authenticate` headers with `resource_metadata` on authentication failures. - **Claim Mapping**: Maps token claims to downstream headers for use by backend services. @@ -21,7 +21,7 @@ The MCP Authentication policy is designed to secure traffic to Model Context Pro The MCP Authentication policy uses a two-level configuration model: -### System Parameters (config.toml) +### System parameters (config.toml) Configured by the administrator in `config.toml` under `policy_configurations.mcpauth_v1` or `policy_configurations.jwtauth_v1` depending on the parameter. @@ -42,7 +42,7 @@ Configured by the administrator in `config.toml` under `policy_configurations.mc | `validateIssuer` | boolean | No | - | jwtauth_v1 | Whether to validate the token's issuer claim against configured key managers. | | `gatewayHost` | string | No | `"localhost"` | mcpauth_v1 | The outward-facing gateway host name used when deriving the protected resource metadata URL and response. | -#### KeyManager Configuration +#### KeyManager configuration Each key manager in the `keyManagers` array supports the following structure: @@ -58,7 +58,7 @@ Each key manager in the `keyManagers` array supports the following structure: > **Note**: Either `jwks.remote` or `jwks.local` must be specified, but not both. -#### System Configuration Example +#### System configuration example ```toml [policy_configurations.mcpauth_v1] @@ -95,11 +95,11 @@ uri = "https://auth.example.org/oauth2/jwks" skipTlsVerify = false ``` -### User Parameters (API Definition) +### User parameters (API definition) These parameters are configured per-API/route by the API developer: -#### Resource Type Configuration +#### Resource type configuration | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| @@ -111,7 +111,7 @@ These parameters are configured per-API/route by the API developer: | `requiredScopes` | string array | No | `[]` | List of scopes that should be included in the token generated through MCP auth flow. These are advertised in the protected resource metadata but **not enforced** by this policy. Use the MCP Authorization policy to enforce scopes. | | `claimMappings` | object | No | `{}` | Map of claimName → downstream header or context key to expose claims for downstream services. | -#### SecurityConfig Object +#### SecurityConfig object Each resource type configuration supports the following structure: @@ -129,9 +129,9 @@ Inside the `gateway/build.yaml`, ensure the policy module is added under `polici gomodule: github.com/wso2/gateway-controllers/policies/mcp-auth@v0 ``` -## Reference Scenarios +## Reference scenarios -### Example 1: Basic MCP Authentication +### Example 1: Basic MCP authentication Apply MCP authentication to an API using a specific key manager: @@ -157,7 +157,7 @@ spec: ... ``` -### Example 2: Disable Security for Specific Tools +### Example 2: Disable security for specific tools Disable authentication for specific tools while keeping it enabled for others: @@ -194,7 +194,7 @@ spec: ... ``` -### Example 3: Scope Advertisement in Protected Resource Metadata +### Example 3: Scope advertisement in protected resource metadata Advertise required scopes in the protected resource metadata (scopes are not enforced by this policy): @@ -223,7 +223,7 @@ spec: ... ``` -### Example 4: Claim Mapping for Downstream Services +### Example 4: Claim mapping for downstream services Map JWT claims to downstream headers for use by backend services: @@ -253,7 +253,7 @@ spec: ... ``` -### Example 5: Disable Authentication for Resources +### Example 5: Disable authentication for resources Completely disable authentication for MCP resources while keeping it for tools: diff --git a/en/docs/cloud/ai-gateway/mcp/policies/mcp-authorization.md b/en/docs/cloud/ai-gateway/mcp/policies/mcp-authorization.md index 239d4dcc..f3c372e1 100644 --- a/en/docs/cloud/ai-gateway/mcp/policies/mcp-authorization.md +++ b/en/docs/cloud/ai-gateway/mcp/policies/mcp-authorization.md @@ -1,7 +1,7 @@ --- title: "Overview" --- -# MCP Authorization +# MCP authorization ## Overview @@ -25,7 +25,7 @@ The MCP Authorization policy provides fine-grained access control for Model Cont The MCP Authorization policy uses a single-level configuration model where all parameters are configured per-MCP-API/route in the API definition YAML. -### User Parameters (API Definition) +### User parameters (API definition) These parameters are configured per MCP Proxy by the API developer: @@ -36,7 +36,7 @@ These parameters are configured per MCP Proxy by the API developer: | `prompts` | `AuthzRule` array | No | `[]` | Authorization rules for MCP prompts. | | `methods` | `AuthzRule` array | No | `[]` | Authorization rules for MCP (JSON-RPC) methods. | -### AuthzRule Configuration +### AuthzRule configuration Each authorization rule object supports the following fields: @@ -57,9 +57,9 @@ Inside the `gateway/build.yaml`, ensure the policy module is added under `polici gomodule: github.com/wso2/gateway-controllers/policies/mcp-authz@v0 ``` -## Reference Scenarios +## Reference scenarios -### Example 1: Basic Tool Access Control +### Example 1: Basic tool access control Restrict access to specific tools based on scopes: @@ -114,7 +114,7 @@ spec: - `name="*", requiredScopes=["mcp:tool:execute"]` - Result: ✅ Access Granted (both matching rules pass) -### Example 2: Claim-Based Resource Access +### Example 2: Claim-based resource access Control resource access based on user claims: @@ -166,7 +166,7 @@ spec: - Rule: `name="file:///private/main", requiredClaims={department="engineering"}, requiredScopes=["mcp:resource:read"]` - Result: ❌ Access Denied (scope mismatch) -### Example 3: Role-Based Prompt Access +### Example 3: Role-based prompt access Restrict prompt access based on user roles: @@ -204,7 +204,7 @@ spec: ... ``` -### Example 4: Method-Level Authorization +### Example 4: Method-level authorization Apply authorization at the JSON-RPC method level: @@ -245,7 +245,7 @@ spec: ... ``` -### Example 5: Multi-Level Authorization +### Example 5: Multi-level authorization Combine different resource types with varying access requirements: @@ -304,7 +304,7 @@ spec: ... ``` -## Authorization Logic +## Authorization logic The MCP Authorization policy evaluates rules using the following logic: @@ -330,7 +330,7 @@ When authorization fails, the policy returns: - **Response Body**: JSON error response with a reason message - **WWW-Authenticate Header**: Contains information about required scopes for the denied resource -## Related Policies +## Related policies - [MCP Authentication Policy](./mcp-authentication.md) - Validates JWT tokens and is a prerequisite for MCP Authorization - [JWT Authentication Policy](https://wso2.com/api-platform/policy-hub/policies/jwt-auth) - Base JWT token validation mechanism diff --git a/en/docs/cloud/ai-gateway/mcp/policies/mcp-rewrite.md b/en/docs/cloud/ai-gateway/mcp/policies/mcp-rewrite.md index 3089874c..ed4b1cc9 100644 --- a/en/docs/cloud/ai-gateway/mcp/policies/mcp-rewrite.md +++ b/en/docs/cloud/ai-gateway/mcp/policies/mcp-rewrite.md @@ -1,7 +1,7 @@ --- title: "Overview" --- -# MCP Rewrite +# MCP rewrite ## Overview @@ -11,17 +11,17 @@ When a list is provided for a capability type, only the configured capabilities ## Features -- **Tool Rewriting**: Define user-facing tool names and map them to backend tool names with custom schemas and descriptions. -- **Resource Rewriting**: Define user-facing resource identifiers and map them to backend resource identifiers with custom descriptions. -- **Prompt Rewriting**: Define user-facing prompt names and map them to backend prompt names with custom metadata. -- **Flexible Metadata**: Include additional fields (beyond `name`, `description`, `target`, etc.) in capability definitions for custom metadata in list responses. -- **Optional Mapping**: Omit the `target` field to expose capabilities as-is without mapping to a different backend name. +- **Tool rewriting**: Define user-facing tool names and map them to backend tool names with custom schemas and descriptions. +- **Resource rewriting**: Define user-facing resource identifiers and map them to backend resource identifiers with custom descriptions. +- **Prompt rewriting**: Define user-facing prompt names and map them to backend prompt names with custom metadata. +- **Flexible metadata**: Include additional fields (beyond `name`, `description`, `target`, etc.) in capability definitions for custom metadata in list responses. +- **Optional mapping**: Omit the `target` field to expose capabilities as-is without mapping to a different backend name. ## Configuration The MCP Rewrite policy uses a single-level configuration model where all parameters are configured per-MCP-API/route in the API definition YAML. -### User Parameters (API Definition) +### User parameters (API definition) These parameters are configured per MCP Proxy by the API developer: @@ -33,7 +33,7 @@ These parameters are configured per MCP Proxy by the API developer: > **Note**: At least one of `tools`, `resources`, or `prompts` must be specified. -### ToolRewriteConfig Configuration +### ToolRewriteConfig configuration Each `ToolRewriteConfig` object supports the following fields: @@ -45,7 +45,7 @@ Each `ToolRewriteConfig` object supports the following fields: | `outputSchema` | string | No | - | Tool output schema returned in `tools/list`. | | `target` | string | No | - | Backend tool name to use when forwarding requests. If omitted, `name` is used. | -### ResourceRewriteConfig Configuration +### ResourceRewriteConfig configuration Each `ResourceRewriteConfig` object supports the following fields: @@ -56,7 +56,7 @@ Each `ResourceRewriteConfig` object supports the following fields: | `description` | string | No | - | User-facing resource description returned in `resources/list`. | | `target` | string | No | - | Backend resource identifier (URI) to use when forwarding requests. If omitted, `uri` is used. | -### PromptRewriteConfig Configuration +### PromptRewriteConfig configuration Each `PromptRewriteConfig` object supports the following fields: @@ -77,9 +77,9 @@ Inside the `gateway/build.yaml`, ensure the policy module is added under `polici gomodule: github.com/wso2/gateway-controllers/policies/mcp-rewrite@v0 ``` -## Reference Scenarios +## Reference scenarios -### Example 1: Basic Tool Rewriting +### Example 1: Basic tool rewriting Expose tools with different names than the backend: @@ -111,7 +111,7 @@ spec: ... ``` -### Example 2: Resource Rewriting with URI Mapping +### Example 2: Resource rewriting with URI mapping Expose resources with user-friendly URIs mapped to backend resources: @@ -143,7 +143,7 @@ spec: ... ``` -### Example 3: Prompt and Tool Rewriting Combined +### Example 3: Prompt and tool rewriting combined Rewrite prompts and tools with metadata: diff --git a/en/docs/cloud/ai-gateway/mcp/quick-start-guide.md b/en/docs/cloud/ai-gateway/mcp/quick-start-guide.md index a6c7e228..92b82c8f 100644 --- a/en/docs/cloud/ai-gateway/mcp/quick-start-guide.md +++ b/en/docs/cloud/ai-gateway/mcp/quick-start-guide.md @@ -1,6 +1,6 @@ -## Quick Start +## Quick start -### Using Docker Compose (Recommended) +### Using Docker compose (recommended) ### Prerequisites @@ -76,7 +76,7 @@ To test MCP traffic routing through the gateway, add the following URL to your M http://localhost:8080/everything/mcp ``` -## Stopping the Gateway +## Stopping the gateway Stop and remove the MCP backend first. diff --git a/en/docs/cloud/ai-gateway/observability/index.md b/en/docs/cloud/ai-gateway/observability/index.md index ef45d518..d11fbe7f 100644 --- a/en/docs/cloud/ai-gateway/observability/index.md +++ b/en/docs/cloud/ai-gateway/observability/index.md @@ -2,7 +2,7 @@ The AI Gateway observability docs explain how to collect and inspect operational telemetry from gateway components. -## In This Section +## In this section - [Gateway Logging](logging.md) for centralized log collection and log search - [Gateway Tracing](tracing.md) for distributed tracing with OpenTelemetry and Jaeger diff --git a/en/docs/cloud/ai-gateway/observability/logging.md b/en/docs/cloud/ai-gateway/observability/logging.md index 26099b31..c7818955 100644 --- a/en/docs/cloud/ai-gateway/observability/logging.md +++ b/en/docs/cloud/ai-gateway/observability/logging.md @@ -1,4 +1,4 @@ -# Gateway Logging +# Gateway logging This guide explains how to implement and configure logging for the API Platform Gateway components. @@ -8,7 +8,7 @@ The default logging services included in the Docker Compose configuration are ** **Important**: You are free to choose any logging or observability strategy that suits your environment and requirements. The provided setup is just one of many possible configurations. -## Logging Architecture +## Logging architecture The default logging stack consists of: @@ -16,7 +16,7 @@ The default logging stack consists of: - **OpenSearch**: Stores and indexes log data for searchability and analysis - **OpenSearch Dashboards**: Web interface for visualizing, exploring, and searching logs -### How It Works +### How it works 1. Gateway components (gateway-controller, policy-engine, router) write structured JSON logs to stdout/stderr 2. Docker captures these logs and stores them in `/var/lib/docker/containers` @@ -24,9 +24,9 @@ The default logging stack consists of: 4. Fluent Bit forwards processed logs to OpenSearch 5. Users can view and search logs through OpenSearch Dashboards -## Enabling Logging Services +## Enabling logging services -### Gateway Components Already Log to Standard Output +### Gateway components already log to standard output **No special configuration is required to enable logging in the gateway components.** All gateway components (gateway-controller, policy-engine, and router) follow the [12-factor app](https://12factor.net/logs) architecture principle for logging: @@ -36,13 +36,13 @@ The default logging stack consists of: This architecture approach allows you to utilize **any industry-standard logging stack** to collect logs from Docker container log files and view them in your preferred observability platform. The gateway components are completely decoupled from the logging infrastructure. -### Demonstrated Logging Services +### Demonstrated logging services The logging services included in the Docker Compose file (OpenSearch, OpenSearch Dashboards, and Fluent Bit) are provided as **demonstration services** to show one possible way to collect and visualize logs. You can use them as-is for development/testing, or replace them with your own logging solution. The gateway uses Docker Compose profiles to optionally enable these demonstration logging services. -### Start Gateway with Demonstrated Logging Services +### Start gateway with demonstrated logging services To start the gateway with the demonstration logging services enabled: @@ -56,7 +56,7 @@ This starts: - OpenSearch Dashboards - *web UI for viewing logs* - Fluent Bit - *collects logs from Docker and forwards to OpenSearch* -### Start Gateway without Logging Services +### Start gateway without logging services To run only the core gateway services without the demonstration logging stack: @@ -72,7 +72,7 @@ docker logs policy-engine docker logs router ``` -### Stop Logging Services +### Stop logging services To stop all services including the logging stack: @@ -88,7 +88,7 @@ docker compose --profile logging down -v This removes the `opensearch-data` volume containing all stored logs. -## Viewing Logs in OpenSearch Dashboards +## Viewing logs in OpenSearch Dashboards Once you've started the gateway with the logging profile, follow these steps to view component logs: @@ -99,7 +99,7 @@ Open your browser and navigate to: http://localhost:5601 ``` -### Step 2: Create an Index Pattern +### Step 2: Create an index pattern Before you can view logs, you need to create an index pattern: @@ -112,7 +112,7 @@ Before you can view logs, you need to create an index pattern: 7. Select **@timestamp** as the time field 8. Click **Create index pattern** -### Step 3: Navigate to Discover +### Step 3: Navigate to discover To view and explore logs: @@ -121,11 +121,11 @@ To view and explore logs: 3. Select the `gateway-logs-*` index pattern from the dropdown in the top-left 4. Adjust the time range in the top-right corner if needed (default is last 15 minutes) -### Step 4: Filter Logs by Component +### Step 4: Filter logs by component To view logs for a specific gateway component, use filters: -#### View Policy Engine Logs +#### View policy engine logs 1. Click **Add filter** (below the search bar) 2. **Field**: Select `component` @@ -133,7 +133,7 @@ To view logs for a specific gateway component, use filters: 4. **Value**: Enter `policy-engine` 5. Click **Save** -#### View Gateway Controller Logs +#### View gateway controller logs 1. Click **Add filter** 2. **Field**: `component` @@ -141,7 +141,7 @@ To view logs for a specific gateway component, use filters: 4. **Value**: `gateway-controller` 5. Click **Save** -#### View Router (Envoy) Logs +#### View router (envoy) logs 1. Click **Add filter** 2. **Field**: `component` @@ -149,11 +149,11 @@ To view logs for a specific gateway component, use filters: 4. **Value**: `router` 5. Click **Save** -### Step 5: Search and Filter Logs +### Step 5: Search and filter logs You can refine your log search using: -#### Free Text Search +#### Free text search Enter keywords in the search bar at the top: ``` error @@ -162,19 +162,19 @@ error Weather-API ``` -#### Filter by Log Level +#### Filter by log level 1. Click **Add filter** 2. **Field**: `level` 3. **Operator**: `is` 4. **Value**: `error` (or `info`, `warn`, `debug`) -#### Combine Multiple Filters +#### Combine multiple filters Add multiple filters to narrow down results. For example: - Component: `policy-engine` - Level: `error` - Time range: Last 1 hour -#### Example Search Queries +#### Example search queries Search for errors in the policy engine: ``` @@ -191,18 +191,18 @@ Search for slow requests (if duration field exists): duration_ms:>1000 ``` -### Step 6: Customize Log View +### Step 6: Customize log view -- **Add/Remove Columns**: Click the **gear icon** next to the field list to select which fields to display +- **Add/remove columns**: Click the **gear icon** next to the field list to select which fields to display - **Sort**: Click column headers to sort by that field -- **Expand Logs**: Click the **>** arrow next to any log entry to see full details in JSON format -- **Save Search**: Click **Save** in the top menu to save your filters and queries for later use +- **Expand logs**: Click the **>** arrow next to any log entry to see full details in JSON format +- **Save search**: Click **Save** in the top menu to save your filters and queries for later use -## Alternative Logging Stacks +## Alternative logging stacks While the default setup uses OpenSearch and Fluent Bit, you can integrate with other logging platforms: -### Elastic Stack (ELK) +### Elastic stack (ELK) Replace OpenSearch with the Elastic Stack: @@ -272,7 +272,7 @@ grafana: - loki ``` -### Cloud-Native Solutions +### Cloud-native solutions #### AWS CloudWatch @@ -325,7 +325,7 @@ Configure Fluent Bit to forward to Splunk HEC: ``` -## Additional Resources +## Additional resources - [Fluent Bit Documentation](https://docs.fluentbit.io/) - [OpenSearch Documentation](https://opensearch.org/docs/latest/) diff --git a/en/docs/cloud/ai-gateway/observability/tracing.md b/en/docs/cloud/ai-gateway/observability/tracing.md index 924fe982..e648a991 100644 --- a/en/docs/cloud/ai-gateway/observability/tracing.md +++ b/en/docs/cloud/ai-gateway/observability/tracing.md @@ -1,4 +1,4 @@ -# Gateway Tracing +# Gateway tracing This guide explains how to implement and configure distributed tracing for the API Platform Gateway components. @@ -8,14 +8,14 @@ The default tracing services included in the Docker Compose configuration are ** **Important**: You are free to choose any tracing or observability strategy that suits your environment and requirements. The provided setup is just one of many possible configurations. -## Tracing Architecture +## Tracing architecture The default tracing stack consists of: - **OpenTelemetry (OTLP) Collector**: Receives, processes, and exports trace data from gateway components - **Jaeger**: Stores and visualizes distributed traces with a web UI for trace exploration and analysis -### How It Works +### How it works 1. Gateway components (gateway-controller, policy-engine, router) are configured to export traces via OTLP (OpenTelemetry Protocol) 2. Components send trace spans to the OpenTelemetry Collector via gRPC (port 4317) or HTTP (port 4318) @@ -23,22 +23,22 @@ The default tracing stack consists of: 4. The OTLP Collector forwards traces to Jaeger for storage and visualization 5. Users can view and analyze traces through the Jaeger UI -### What is Distributed Tracing? +### What is distributed tracing? Distributed tracing tracks a request as it flows through multiple components: - **Trace**: Represents the entire journey of a request through the system - **Span**: Represents a single operation within a trace (e.g., policy execution, upstream call) -- **Context Propagation**: Traces are correlated across components using trace IDs and span IDs in headers +- **Context propagation**: Traces are correlated across components using trace IDs and span IDs in headers -## Enabling Tracing +## Enabling tracing -### Configuration Required +### Configuration required You need to enable tracing in the gateway configuration file and point it to your OTLP collector endpoint. The tracing configuration is located in `gateway/configs/config.toml`: -#### Policy Engine Tracing Configuration +#### Policy engine tracing configuration ```toml [tracing] @@ -50,13 +50,13 @@ max_export_batch_size = 512 # Maximum spans per batch sampling_rate = 1.0 # Sample rate (1.0 = 100%, 0.5 = 50%) ``` -### Demonstrated Tracing Services +### Demonstrated tracing services The tracing services included in the Docker Compose file (Jaeger and OpenTelemetry Collector) are provided as **demonstration services** to show one possible way to collect and visualize traces. You can use them as-is for development/testing, or replace them with your own tracing solution. The gateway uses Docker Compose profiles to optionally enable these demonstration tracing services. -### Start Gateway with Demonstrated Tracing Services +### Start gateway with demonstrated tracing services To start the gateway with the demonstration tracing services enabled: @@ -69,7 +69,7 @@ This starts: - OpenTelemetry Collector - *receives and processes traces* - Jaeger - *stores and visualizes traces* -### Start Gateway without Tracing Services +### Start gateway without tracing services To run only the core gateway services without the demonstration tracing stack: @@ -79,7 +79,7 @@ docker compose up -d **Note:** If tracing is enabled in the configuration but the OTLP collector is not running, components will log warnings about failed trace exports. To completely disable tracing, set `enabled = false` in the configuration. -### Stop Tracing Services +### Stop tracing services To stop all services including the tracing stack: @@ -89,7 +89,7 @@ docker compose --profile tracing down **Note:** Jaeger stores traces in memory by default. Stopping the service will lose all trace data. For persistent storage, configure Jaeger with a backend database (see Jaeger documentation). -## Viewing Traces in Jaeger +## Viewing traces in Jaeger Once you've started the gateway with the tracing profile, follow these steps to view distributed traces: @@ -100,7 +100,7 @@ Open your browser and navigate to: http://localhost:16686 ``` -### Step 2: Search for Traces +### Step 2: Search for traces The Jaeger UI provides several ways to search for traces: @@ -112,28 +112,28 @@ The Jaeger UI provides several ways to search for traces: - Choose "all" to see all operations - Or select a specific operation (e.g., specific policy execution) -3. **Adjust Lookback Time Range**: +3. **Adjust lookback time range**: - Default: Last 1 hour - Options: 5m, 15m, 1h, 6h, 12h, 1d, 2d, Custom -4. **Add Filters** (optional): +4. **Add filters** (optional): - **Tags**: Filter by specific tag values (e.g., `http.status_code=500`) - **Min/Max Duration**: Filter by trace duration - **Limit Results**: Control number of traces returned (default: 20) 5. Click **Find Traces** -### Step 3: Analyze Trace Details +### Step 3: Analyze trace details Click on any trace in the results to view detailed information: -#### Trace Timeline +#### Trace timeline - **Visual timeline** showing all spans in the trace - **Duration bars** showing relative time spent in each operation - **Parent-child relationships** between spans - **Color coding** by service -#### Span Details +#### Span details Click on any span to see: - **Operation name**: What operation was performed - **Duration**: How long it took @@ -141,40 +141,40 @@ Click on any span to see: - **Logs**: Events logged during the span (errors, warnings, etc.) - **Process**: Service name, version, and host information -#### Common Use Cases +#### Common use cases -**Finding Slow Requests:** +**Finding slow requests:** 1. Set Min Duration filter (e.g., 1000ms) 2. Click Find Traces 3. Examine spans to identify bottlenecks -**Debugging Errors:** +**Debugging errors:** 1. Filter by tag: `error=true` or `http.status_code=500` 2. Click on error traces 3. Examine span logs and tags for error details -**Understanding Request Flow:** +**Understanding request flow:** 1. Search for a specific trace ID (from logs or headers) 2. View the complete request path through all components 3. Identify which component handled which part of the request -### Step 4: Trace Comparison +### Step 4: Trace comparison You can compare multiple traces to identify patterns: 1. Select multiple traces using checkboxes 2. Click **Compare Traces** button 3. View side-by-side comparison of trace structure and timings -### Step 5: Service Dependency Graph +### Step 5: Service dependency graph View how services interact: 1. Click **Dependencies** in the top navigation 2. Select time range 3. View graph showing service-to-service communication patterns -## Configuration Options +## Configuration options -### Adjusting Sampling Rate +### Adjusting sampling rate To reduce trace volume in high-traffic environments, adjust the sampling rate: @@ -192,7 +192,7 @@ Sampling strategies: **Note:** Lower sampling rates reduce overhead but may miss important traces. -### Custom Service Names +### Custom service names Customize service names for better identification: @@ -201,7 +201,7 @@ Customize service names for better identification: service_name = "policy-engine-prod-us-east-1" ``` -### Batch Configuration +### Batch configuration Optimize batch settings for your environment: @@ -214,7 +214,7 @@ max_export_batch_size = 1024 # Export up to 1024 spans per batch **Lower timeout**: Faster trace visibility, more network overhead **Higher timeout**: Better batching efficiency, slower trace visibility -## Alternative Tracing Backends +## Alternative tracing backends While the default setup uses Jaeger, the gateway components use OpenTelemetry and can export to any OTLP-compatible backend. @@ -244,12 +244,12 @@ service: exporters: [otlphttp] # Send to Moesif ``` -**Important Notes:** +**Important notes:** - The endpoint uses HTTPS (not HTTP) - Use the `otlphttp` exporter (not `otlp` which uses gRPC) - The `X-Moesif-Application-Id` header is required for authentication -#### Obtaining Your Moesif Application ID +#### Obtaining your Moesif application ID 1. Sign up for a Moesif account at [moesif.com](https://www.moesif.com) 2. Log in to your Moesif dashboard @@ -257,7 +257,7 @@ service: 4. Locate the **Collector Application ID** field 5. Copy your unique Application ID -#### Using Environment Variables +#### Using environment variables For better security, use environment variables for the Application ID: @@ -286,7 +286,7 @@ export MOESIF_APPLICATION_ID=your-moesif-application-id docker compose --profile tracing up -d ``` -#### Accessing Moesif Dashboard +#### Accessing Moesif dashboard After configuring and starting the gateway: @@ -296,16 +296,16 @@ After configuring and starting the gateway: 4. Use **Time Series** to analyze API usage trends 5. Set up **Alerts** for error rates, latency, or custom conditions -#### Moesif Features +#### Moesif features - **API Analytics**: Request volume, response times, error rates -- **User Tracking**: Identify and track API users across requests -- **Error Analysis**: Detailed error tracking with request/response bodies +- **User tracking**: Identify and track API users across requests +- **Error analysis**: Detailed error tracking with request/response bodies - **Behavioral Cohorts**: Group users by API usage patterns - **Custom Dashboards**: Build visualizations for your specific KPIs - **Alerting**: Get notified of anomalies or threshold breaches -#### Sending to Both Jaeger and Moesif +#### Sending to both Jaeger and Moesif You can send traces to both Jaeger (for development) and Moesif (for analytics): @@ -392,7 +392,7 @@ tracing: endpoint: tempo:4317 ``` -### Cloud-Native Tracing Solutions +### Cloud-native tracing solutions #### AWS X-Ray @@ -502,7 +502,7 @@ exporters: lightstep-access-token: ${LIGHTSTEP_ACCESS_TOKEN} ``` -### Service Mesh Integration +### Service mesh integration If using a service mesh like Istio or Linkerd: @@ -533,7 +533,7 @@ The OTLP Collector configuration is located at: gateway/observability/otel-collector/config.yaml ``` -### Configuration Structure +### Configuration structure The configuration consists of three main sections: @@ -598,7 +598,7 @@ exporters: sampling_thereafter: 200 ``` -#### Service Pipeline +#### Service pipeline Connect receivers, processors, and exporters: ```yaml @@ -610,7 +610,7 @@ service: exporters: [otlp, debug] ``` -### Example: Multi-Backend Export +### Example: Multi-backend export Send traces to multiple backends simultaneously: @@ -638,7 +638,7 @@ service: exporters: [otlp/jaeger, otlp/tempo, datadog] ``` -### Example: Tail-Based Sampling +### Example: Tail-based sampling Keep all error traces but sample successful traces: @@ -660,7 +660,7 @@ processors: sampling_percentage: 10 ``` -## Trace Context Propagation +## Trace context propagation The gateway components automatically propagate trace context using standard W3C Trace Context headers: @@ -679,7 +679,7 @@ curl http://localhost:8080/weather/v1.0/us/seattle \ This allows you to trace requests across your entire system, including services before and after the gateway. -## Best Practices +## Best practices ### Development - Use 100% sampling rate (`sampling_rate: 1.0`) @@ -710,7 +710,7 @@ This allows you to trace requests across your entire system, including services - Use asynchronous trace export (default with OTLP) - Consider using tail-based sampling for high-volume environments -### Sampling Strategy +### Sampling strategy Choose sampling based on traffic volume: @@ -725,7 +725,7 @@ Choose sampling based on traffic volume: ## Troubleshooting -### Traces Not Appearing in Jaeger +### Traces not appearing in Jaeger **1. Verify tracing is enabled in configuration:** ```bash @@ -764,14 +764,14 @@ docker logs policy-engine | grep -i trace docker logs gateway-controller | grep -i trace ``` -### Traces Are Incomplete or Missing Spans +### Traces are incomplete or missing spans **1. Check sampling rate** - ensure it's not too low **2. Verify all components are configured** to export traces **3. Check for trace context propagation issues** - ensure headers are preserved **4. Look for timeout errors** in OTLP collector logs -### High Trace Export Overhead +### High trace export overhead **1. Reduce sampling rate:** ```toml @@ -788,13 +788,13 @@ max_export_batch_size = 2048 **3. Use tail-based sampling** in OTLP collector to sample only important traces -### Traces Have Incorrect Timing +### Traces have incorrect timing - **Ensure system clocks are synchronized** across all containers (use NTP) - **Check for clock skew** in trace timeline view - **Verify trace context propagation** is working correctly -### Cannot Access Jaeger UI +### Cannot access Jaeger UI **1. Verify Jaeger is running:** ```bash @@ -811,7 +811,7 @@ docker logs jaeger curl http://localhost:16686/ ``` -## Disabling Tracing +## Disabling tracing To completely disable tracing: @@ -833,11 +833,11 @@ docker compose restart gateway-controller policy-engine router **Note:** The router (Envoy) tracing is controlled by the gateway-controller configuration and will be disabled when the configuration is updated. -## Integration with Logging +## Integration with logging Traces and logs work together for comprehensive observability: -### Correlating Traces and Logs +### Correlating traces and logs 1. **Trace ID in Logs**: Gateway components include trace IDs in log entries 2. **Find Trace from Log**: Copy trace ID from log entry and search in Jaeger @@ -855,7 +855,7 @@ Example log entry with trace ID: } ``` -### Using Both Stacks +### Using both stacks Enable both logging and tracing profiles: @@ -867,7 +867,7 @@ This provides complete observability: - **Traces**: Request flow and performance - **Logs**: Detailed event information and debugging -## Additional Resources +## Additional resources - [OpenTelemetry Documentation](https://opentelemetry.io/docs/) - [Jaeger Documentation](https://www.jaegertracing.io/docs/) diff --git a/en/docs/cloud/ai-gateway/overview.md b/en/docs/cloud/ai-gateway/overview.md index cdfa8733..14dd4ef8 100644 --- a/en/docs/cloud/ai-gateway/overview.md +++ b/en/docs/cloud/ai-gateway/overview.md @@ -1,15 +1,15 @@ -# AI Gateway Overview +# AI Gateway overview The AI Gateway is the standalone runtime plane for routing, securing, and observing AI traffic. It handles Large Language Model (LLM) APIs and Model Context Protocol (MCP) servers, and can run independently or connect to the AI Workspace control plane for centralized management. -## Quick Start +## Quick start - [LLM Quick Start Guide](llm/quick-start-guide.md) - Set up the gateway, verify the controller admin health endpoint, and route traffic to LLM providers like OpenAI - [MCP Quick Start Guide](mcp/quick-start-guide.md) - Set up the gateway, verify the controller admin health endpoint, and route traffic to MCP servers -## Key Concepts +## Key concepts -### LLM Provider Template +### LLM provider template An LLM Provider Template defines the characteristics and behaviors specific to an AI service provider, such as OpenAI, Azure OpenAI, or other LLM platforms. It describes how the gateway should interpret and extract usage and operational metadata, including prompt, completion, total, and remaining token information, as well as request and response model metadata. @@ -22,7 +22,7 @@ Following templates are shipped out-of-the-box - Azure AI Foundry - Gemini -### LLM Provider +### LLM provider An LLM Provider represents a connection from the gateway runtime to an AI backend service such as OpenAI, Azure OpenAI, or other LLM APIs. Administrators configure LLM Providers to define: @@ -35,7 +35,7 @@ An LLM Provider represents a connection from the gateway runtime to an AI backen Once configured, the LLM Provider allows traffic to flow through the gateway to the AI backend. -### LLM Proxy +### LLM proxy An LLM Proxy allows developers to create custom API endpoints that consume an LLM Provider, while inheriting administrator-enforced access control, budgeting and organization-wide policies defined at the provider level. Each proxy gets its own URL context (e.g., `/assistant`) and can have its own policies applied. This enables: @@ -43,7 +43,7 @@ An LLM Proxy allows developers to create custom API endpoints that consume an LL - Per-application policies such as prompt management and guardrails - Separation between platform administration and application development -### MCP Proxy +### MCP proxy An MCP Proxy routes Model Context Protocol traffic to MCP servers. MCP is a protocol that enables AI assistants to interact with external tools and data sources. With MCP Proxies, you can: @@ -51,7 +51,7 @@ An MCP Proxy routes Model Context Protocol traffic to MCP servers. MCP is a prot - Apply authentication and access control to MCP traffic - Manage multiple MCP servers from a single control plane -## Control Plane Integration +## Control plane integration The AI Gateway can be managed in two ways: @@ -60,7 +60,7 @@ The AI Gateway can be managed in two ways: Use AI Workspace when you want a UI-driven control plane for gateway registration, provider and proxy management, policy configuration, and deployment workflows. -## Default Ports +## Default ports | Port | Service | Description | |------|---------|-------------| diff --git a/en/docs/cloud/ai-workspace/ai-gateways/setting-up.md b/en/docs/cloud/ai-workspace/ai-gateways/setting-up.md index e7dd588b..1bbd5274 100644 --- a/en/docs/cloud/ai-workspace/ai-gateways/setting-up.md +++ b/en/docs/cloud/ai-workspace/ai-gateways/setting-up.md @@ -8,7 +8,7 @@ AI Gateways are the runtime components that process and route requests between y --- -## View AI Gateways +## View AI gateways 1. Navigate to **AI Gateways** in the left navigation menu. @@ -24,7 +24,7 @@ The AI Gateways page displays a list of all configured gateways with the followi --- -## Add a New AI Gateway +## Add a new AI Gateway 1. Navigate to **AI Gateways** in the left navigation menu. @@ -48,11 +48,11 @@ The AI Gateways page displays a list of all configured gateways with the followi --- -## Set Up the Gateway +## Set up the gateway After creating an AI gateway, you need to set up the gateway runtime. The detail page provides a **Get Started** section with setup instructions. -### Gateway Registration Token +### Gateway registration token A **Gateway Registration Token** is displayed at the top of the Get Started section. This token is required to connect your gateway runtime to the control plane. @@ -62,7 +62,7 @@ A **Gateway Registration Token** is displayed at the top of the Get Started sect !!! tip "Lost your token?" The registration token is single-use. If you need to reconfigure the gateway, click the **Reconfigure** button to generate a new token. This will revoke the old token and disconnect the gateway from the control plane. -### Installation Methods +### Installation methods The Get Started section provides setup instructions for multiple deployment options: @@ -215,9 +215,9 @@ Once the gateway runtime is running and connected, the gateway status will chang --- -## Manage AI Gateways +## Manage AI gateways -### Edit a Gateway +### Edit a gateway 1. In the AI Gateways list, click the **edit** icon next to the gateway you want to modify. @@ -225,7 +225,7 @@ Once the gateway runtime is running and connected, the gateway status will chang 3. Click **Save** to apply the changes. -### Delete a Gateway +### Delete a gateway 1. In the AI Gateways list, click the **delete** icon (trash icon) next to the gateway you want to remove. @@ -236,7 +236,7 @@ Once the gateway runtime is running and connected, the gateway status will chang --- -## Next Steps +## Next steps - [Configure LLM Provider](../llm-providers/configure-provider.md) - Set up an LLM provider and deploy it to your gateway - [Configure App LLM Proxy](../llm-proxies/configure-proxy.md) - Create a specialized LLM proxy for a Gen AI application or agent and deploy it to your gateway diff --git a/en/docs/cloud/ai-workspace/configure-inbound-auth.md b/en/docs/cloud/ai-workspace/configure-inbound-auth.md index d7a97278..06421f60 100644 --- a/en/docs/cloud/ai-workspace/configure-inbound-auth.md +++ b/en/docs/cloud/ai-workspace/configure-inbound-auth.md @@ -1,14 +1,14 @@ -# Configure Inbound Authentication +# Configure inbound authentication The **Security** tab on both LLM Providers and App LLM Proxies controls how client applications authenticate when calling the deployed gateway endpoint. This is called **inbound authentication** — the key that your application sends to the gateway, as opposed to the upstream API key the gateway uses to call the LLM provider (configured in the **Connection** tab). -## How It Works +## How it works When a provider or proxy is deployed, the gateway enforces inbound authentication on every incoming request. Clients must include a valid API key in the location and under the name you configure in the Security tab. The API key itself is generated by the AI Workspace (shown once at creation, valid for 90 days). The Security tab controls **where** and **under what name** the client must send it. -## Security Tab Fields +## Security tab fields | Field | Description | |-------|-------------| @@ -16,7 +16,7 @@ The API key itself is generated by the AI Workspace (shown once at creation, val | **API Key** / **Key name** | The name of the header or query parameter that must carry the API key. Defaults to `X-API-Key`. | | **Key Location** / **Sent in** | Whether the key is expected in a request `header` or as a `query` parameter. Defaults to `header`. | -## Default Behaviour: X-API-Key Header +## Default behaviour: X-API-key header Out of the box, the gateway expects the API key in the `X-API-Key` request header: @@ -26,7 +26,7 @@ X-API-Key: Most AI SDKs do not send this header automatically, so you need to add it explicitly when initialising the client. See [Invoke via SDKs](using-sdks.md) for code examples. -## Using a Custom Header Name +## Using a custom header name You can change the key name to match what your SDK sends natively. For example, setting the key name to `Authorization` allows clients to pass the key as a Bearer token: @@ -39,7 +39,7 @@ SDKs such as the OpenAI SDK, Mistral SDK, and Azure OpenAI SDK all send an `Auth !!! note The gateway validates the key value regardless of prefix — it strips a leading `Bearer ` before comparing against the stored key. -## Sending the Key as a Query Parameter +## Sending the key as a query parameter If you set **Key Location** to `query`, clients append the key to the request URL instead: @@ -49,7 +49,7 @@ https:///?= This is useful in environments where setting custom request headers is not straightforward. -## Steps to Configure +## Steps to configure 1. Open your LLM Provider or App LLM Proxy and go to the **Security** tab. 2. Set the **API Key** / **Key name** field to the header or query parameter name your application will use. diff --git a/en/docs/cloud/ai-workspace/genai-applications.md b/en/docs/cloud/ai-workspace/genai-applications.md index 6c8fb1a6..e9c7ac58 100644 --- a/en/docs/cloud/ai-workspace/genai-applications.md +++ b/en/docs/cloud/ai-workspace/genai-applications.md @@ -1,4 +1,4 @@ -# GenAI Applications +# GenAI applications GenAI Applications let you represent a real AI application inside the AI Workspace and associate existing API keys with it. This gives you application-level visibility and control instead of tracking usage only at the individual key level. @@ -11,7 +11,7 @@ With GenAI Applications, you can: - improve governance and accountability for shared GenAI workloads - prepare for application-level limits and controls -## When to Use GenAI Applications +## When to use GenAI applications Use a GenAI Application when: @@ -22,7 +22,7 @@ Use a GenAI Application when: Examples include customer support copilots, internal knowledge assistants, document analysis apps, or workflow-specific AI agents. -## How It Works +## How it works The typical flow is: @@ -40,7 +40,7 @@ The same application can have multiple API keys mapped to it. This is useful whe - At least one generated API key - Access to the AI Workspace project where the GenAI Application will be created -## Create a GenAI Application +## Create a GenAI application 1. Navigate to **AI Workspace** in your API Platform dashboard. 2. Open **GenAI Applications** from the left navigation menu. @@ -54,7 +54,7 @@ The same application can have multiple API keys mapped to it. This is useful whe The application is created within the current project and becomes the shared representation of that GenAI workload. -## Attach API Keys to an Application +## Attach API keys to an application After creating the application, attach the API keys that the application already uses. @@ -66,7 +66,7 @@ After creating the application, attach the API keys that the application already Only existing keys are mapped. This workflow does not create new keys. It links previously generated keys to the application so usage can be attributed correctly. -## View and Manage Attached Keys +## View and manage attached keys The GenAI Application details page shows the keys currently mapped to the application. @@ -82,7 +82,7 @@ You can remove mappings for keys that should no longer be associated with the ap Removing a mapping only detaches the key from that GenAI Application. It does not delete the underlying key unless you remove it from the provider or proxy separately. -## Insights for GenAI Applications +## Insights for GenAI applications Once a mapped key is used to invoke the gateway, the gateway can identify the owning GenAI Application and publish analytics accordingly. @@ -98,7 +98,7 @@ This is especially useful for teams that need to understand which GenAI applicat See [Insights](insights.md) for more on the analytics experience. -## Best Practices +## Best practices - Create one GenAI Application per real application or agent workload, not per developer. - Map all keys used by the same application so analytics stay complete. diff --git a/en/docs/cloud/ai-workspace/getting-started.md b/en/docs/cloud/ai-workspace/getting-started.md index 899c9851..9e2dcbde 100644 --- a/en/docs/cloud/ai-workspace/getting-started.md +++ b/en/docs/cloud/ai-workspace/getting-started.md @@ -1,4 +1,4 @@ -# Getting Started +# Getting started The AI Workspace enables you to manage AI gateways and LLM providers. Follow these steps to get started. @@ -15,7 +15,7 @@ An AI gateway is the runtime that processes and routes requests between your app For detailed instructions, see [AI Gateways](ai-gateways/setting-up.md). -## Step 2: Configure an LLM Provider +## Step 2: Configure an LLM provider An LLM provider connects the AI Workspace to an AI service platform like OpenAI, Anthropic, or Azure OpenAI. @@ -27,7 +27,7 @@ An LLM provider connects the AI Workspace to an AI service platform like OpenAI, For detailed instructions, see [Configure LLM Provider](llm-providers/configure-provider.md). -## What's Next +## What's next - [Manage your provider](llm-providers/manage-provider.md) — Configure connection, access control, security, rate limiting, guardrails, and models diff --git a/en/docs/cloud/ai-workspace/insights.md b/en/docs/cloud/ai-workspace/insights.md index 0f873f79..44da3dd3 100644 --- a/en/docs/cloud/ai-workspace/insights.md +++ b/en/docs/cloud/ai-workspace/insights.md @@ -2,16 +2,16 @@ The AI Workspace provides a built-in **Insights** page that gives you real-time visibility into traffic, usage patterns, and performance across your LLM Providers and Proxies. Insights are powered by [Moesif](https://www.moesif.com/), an AI-native API analytics platform, and are available directly within the AI Workspace — no separate Moesif setup is required. -## Accessing Insights +## Accessing insights 1. Navigate to **AI Workspace** in your API Platform dashboard. 2. Click **Insights** in the left navigation sidebar. The Insights page loads an embedded analytics dashboard scoped to your AI Workspace activity. -## What You Can See +## What you can see -### Overview Summary +### Overview summary The overview panel at the top shows key metrics at a glance: @@ -21,15 +21,15 @@ The overview panel at the top shows key metrics at a glance: | **Avg Latency** | The average end-to-end response latency across all requests. | | **Success Rate** | The percentage of requests that completed successfully (non-error responses). | -### Request Trend +### Request trend A time-series chart showing the volume of requests over time. Use this to identify traffic spikes, usage patterns, and the impact of configuration changes on request volume. -### Traffic Split +### Traffic split A breakdown of traffic distribution across your App LLM Proxies or providers. Use this to understand which app proxies or providers are handling the most load and whether traffic is distributed as expected. -### Full Analytics Dashboard +### Full analytics dashboard The full Moesif-powered dashboard embedded in the Insights page provides deeper analytics, including: @@ -40,7 +40,7 @@ The full Moesif-powered dashboard embedded in the Insights page provides deeper - **Error analysis** — Identify error patterns and guardrail interventions. - **Consumer activity** — Monitor which applications or consumers are generating the most traffic. -## Using Insights for Cost and Rate Limit Management +## Using insights for cost and rate limit management The Insights dashboard is particularly useful for tuning your [token-based rate limits](policies/rate-limit/token-based-rate-limit.md): @@ -48,7 +48,7 @@ The Insights dashboard is particularly useful for tuning your [token-based rate 2. Check **per-consumer traffic** to determine appropriate per-consumer limits. 3. Monitor **error rates** to detect rate limit violations (`429 Too Many Requests` responses) and adjust limits accordingly. -## Using Insights for Guardrail Monitoring +## Using insights for guardrail monitoring When guardrails are active, you can use Insights to: diff --git a/en/docs/cloud/ai-workspace/llm-providers/configure-provider.md b/en/docs/cloud/ai-workspace/llm-providers/configure-provider.md index 4a4b55f4..9a6e2a79 100644 --- a/en/docs/cloud/ai-workspace/llm-providers/configure-provider.md +++ b/en/docs/cloud/ai-workspace/llm-providers/configure-provider.md @@ -1,4 +1,4 @@ -# Configure LLM Provider +# Configure LLM provider LLM Providers allow you to connect AI service platforms like OpenAI, Anthropic, and others to the AI Workspace. Once configured, providers can be deployed and used directly through the managed gateway. @@ -11,7 +11,7 @@ LLM Providers allow you to connect AI service platforms like OpenAI, Anthropic, - At least one [AI Gateway created and set up](../ai-gateways/setting-up.md) - API credentials for your LLM provider (API key, access tokens, etc.) -## Add a New Provider +## Add a new provider 1. Navigate to **AI Workspace** in your API Platform dashboard. 2. Select **Service Providers** from the menu. @@ -19,13 +19,13 @@ LLM Providers allow you to connect AI service platforms like OpenAI, Anthropic, ![Add LLM Service Provider panel showing selectable tiles for OpenAI, Mistral, Gemini, Azure OpenAI, Azure AI Foundry, AWS Bedrock, and Anthropic](../../../assets/img/ai-gateway/ai-workspace/llm-provider/select-llm-provider-type.png) -## Configure Provider Details +## Configure provider details After selecting your provider type, fill in the provider configuration form: ![Add LLM Service Provider form with OpenAI selected, showing Name, Version, Description, Context, API Key, and Guardrails fields](../../../assets/img/ai-gateway/ai-workspace/llm-provider/llm-provider-details.png) -### Basic Information +### Basic information 1. **Name*** (Required): Enter a unique name for the provider (e.g., `openai-production`, `anthropic-dev`). @@ -71,7 +71,7 @@ The authentication fields vary depending on the provider you selected: 1. **Upstream URL*** (Required): Enter your Azure AI Foundry endpoint URL. 2. **API Key*** (Required): Enter your Azure AI Foundry API key. -### Add Guardrails (Optional) +### Add guardrails (optional) You can attach policies and guardrails to your provider that apply to all requests: @@ -89,7 +89,7 @@ You can attach policies and guardrails to your provider that apply to all reques !!! info Learn more about available guardrails in the [Guardrails Overview](../policies/guardrails/overview.md). For the full list of policies and their specifications, visit the [Policy Hub](https://wso2.com/api-platform/policy-hub/). -## Save Provider +## Save provider 1. After configuring all settings and adding guardrails (if needed), click **Add Provider**. @@ -97,7 +97,7 @@ You can attach policies and guardrails to your provider that apply to all reques 3. The provider will appear in the providers list. -## Deploy Provider to Gateway +## Deploy provider to gateway After creating your provider, you must deploy it to a gateway before it can be used. @@ -110,7 +110,7 @@ After creating your provider, you must deploy it to a gateway before it can be u 3. Wait for the deployment to complete. The status will change to **Deployed**. -## Get Started +## Get started Once the provider is deployed, the provider details page shows the Invoke URL on the left and a **Get Started** panel on the right. @@ -118,7 +118,7 @@ Once the provider is deployed, the provider details page shows the Invoke URL on Select a gateway from the **Gateways** dropdown to see the base URL for accessing this provider through that gateway. -### API Keys +### API keys Generate an API key to authenticate requests to the deployed gateway. @@ -128,13 +128,13 @@ Generate an API key to authenticate requests to the deployed gateway. !!! danger "Important" API keys are only displayed once. Store it in a secure location immediately — you will not be able to retrieve it again. -### Deployed Gateways +### Deployed gateways The **Deployed Gateways** section lists all gateways this provider is deployed to, along with the host address and deployment status. --- -## Next Steps +## Next steps - [Configure App LLM Proxy](../llm-proxies/configure-proxy.md) - Configure and deploy a specialized proxy endpoint for a Gen AI application or agent using your provider - [Manage Provider](manage-provider.md) - Configure access control, security, rate limiting, and more \ No newline at end of file diff --git a/en/docs/cloud/ai-workspace/llm-providers/manage-provider.md b/en/docs/cloud/ai-workspace/llm-providers/manage-provider.md index d5f6eec5..2571c22d 100644 --- a/en/docs/cloud/ai-workspace/llm-providers/manage-provider.md +++ b/en/docs/cloud/ai-workspace/llm-providers/manage-provider.md @@ -1,4 +1,4 @@ -# Manage LLM Provider +# Manage LLM provider After deploying your LLM Provider, manage its configuration through the provider details page. This guide covers all management operations organized by tab. @@ -19,7 +19,7 @@ After deploying your LLM Provider, manage its configuration through the provider --- -## Access Provider Details +## Access provider details 1. Navigate to **AI Workspace** > **LLM Providers**. @@ -40,7 +40,7 @@ Manage upstream endpoint configuration and authentication credentials for the LL -### Provider Endpoint +### Provider endpoint **Upstream URL** - Where API requests are forwarded to: @@ -63,7 +63,7 @@ Configure how the gateway authenticates with the upstream provider: - Click the 👁️ icon to show/hide the value - Update and click **Save** to change credentials -### OpenAPI Specification +### OpenAPI specification **Spec URL** - The OpenAPI specification for importing API resources: @@ -73,7 +73,7 @@ Configure how the gateway authenticates with the upstream provider: --- -## Access Control +## Access control
@@ -97,7 +97,7 @@ Use the arrow buttons between the two panels to move resources: - **`<`** — Move selected resource(s) back - **`<<`** — Move all resources back -### Import Resources +### Import resources Click **Import resources from specification** to load or refresh the resource list from the provider's OpenAPI specification. @@ -111,7 +111,7 @@ Configure how applications authenticate when accessing this provider through the
-### API Key Authentication +### API key authentication Set up the API key that client applications must provide: @@ -132,7 +132,7 @@ Set up the API key that client applications must provide: --- -## Rate Limiting +## Rate limiting
@@ -158,7 +158,7 @@ Both sections support two configuration modes: !!! note Provider-wide and Per Resource modes are mutually exclusive per section. Clear existing limits before switching modes. -### Limit Criteria +### Limit criteria Each section lets you configure: @@ -170,14 +170,14 @@ Each section lets you configure: For each enabled criterion, set the **Quota** and **Reset Duration** (`second`, `minute`, or `hour`). -### Provider-wide Configuration +### Provider-wide configuration 1. Select **Provider-wide** in the Backend section. 2. Enable **Request Count** and/or **Token Count**. 3. Enter the **Quota** and select the **Reset Duration** for each criterion. 4. Click **Save**. -### Per Resource Configuration +### Per resource configuration 1. Select **Per Resource** in the Backend section. 2. Expand **Limit per Resource** to set default limits for all endpoints: @@ -200,7 +200,7 @@ Attach guardrails to enforce content safety, compliance, and quality standards.
-### View Attached Guardrails +### View attached guardrails The tab displays all guardrails currently attached to the provider: @@ -208,7 +208,7 @@ The tab displays all guardrails currently attached to the provider: - **Configuration status** and parameters - **Enable/disable toggles** for quick activation control -### Add a Guardrail +### Add a guardrail Guardrails can be added globally (applying to all endpoints) or per resource (applying to a specific endpoint). @@ -228,7 +228,7 @@ Guardrails can be added globally (applying to all endpoints) or per resource (ap 3. Select and configure the guardrail (same process as global guardrails). 4. Click **Add** to attach it to the resource. -### Configure Guardrails +### Configure guardrails Guardrail parameters cannot be edited in place. To change a guardrail's configuration, you must delete it and add it again with the updated settings. @@ -256,7 +256,7 @@ Configure which AI models are accessible through this provider. -### Add Models +### Add models **To add new models:** @@ -265,7 +265,7 @@ Configure which AI models are accessible through this provider. 3. Click **Add** 4. The models are added and enabled by default -### Enable/Disable Models +### Enable/Disable models Control which models applications can access: @@ -275,11 +275,11 @@ Control which models applications can access: --- -## Lifecycle Operations +## Lifecycle operations --- -### Redeploy Provider +### Redeploy provider Push configuration changes to deployed gateways. @@ -301,7 +301,7 @@ Push configuration changes to deployed gateways. --- -### Delete Provider +### Delete provider Permanently remove the provider and all its configurations. @@ -325,7 +325,7 @@ Permanently remove the provider and all its configurations. --- -## Next Steps +## Next steps - [Configure App LLM Proxy](../llm-proxies/configure-proxy.md) - Configure and deploy specialized proxy endpoints for Gen AI applications or agents using your provider - [Policies Overview](../policies/overview.md) - Explore all available guardrails and policies diff --git a/en/docs/cloud/ai-workspace/llm-providers/overview.md b/en/docs/cloud/ai-workspace/llm-providers/overview.md index 7d3fea71..329112b9 100644 --- a/en/docs/cloud/ai-workspace/llm-providers/overview.md +++ b/en/docs/cloud/ai-workspace/llm-providers/overview.md @@ -1,4 +1,4 @@ -# LLM Providers Overview +# LLM providers overview LLM Providers are integrations with AI service platforms that offer language models. By configuring providers in the AI Workspace, you can: @@ -7,7 +7,7 @@ LLM Providers are integrations with AI service platforms that offer language mod - **Monitor provider status**: Track availability and health of connected services - **Simplify configuration**: Use providers across multiple proxies without duplicating credentials -## Supported Providers +## Supported providers API Platform AI Workspace supports the following LLM providers: diff --git a/en/docs/cloud/ai-workspace/llm-proxies/configure-proxy.md b/en/docs/cloud/ai-workspace/llm-proxies/configure-proxy.md index b1692df2..a4281bf0 100644 --- a/en/docs/cloud/ai-workspace/llm-proxies/configure-proxy.md +++ b/en/docs/cloud/ai-workspace/llm-proxies/configure-proxy.md @@ -1,4 +1,4 @@ -# Configure App LLM Proxy +# Configure app LLM proxy An App LLM Proxy exposes a managed endpoint that your Gen AI applications or agents use to reach an LLM Provider. Once deployed, the proxy handles authentication and enforces any guardrails you configure. While the provider can be called directly, the proxy lets you create specialized endpoints for different applications, agents, or environments with independent keys, guardrails, and access controls on top of the same provider. @@ -12,7 +12,7 @@ This guide walks you through creating an App LLM Proxy, optionally attaching gua --- -## Create a New App LLM Proxy +## Create a new app LLM proxy 1. Navigate to **LLM** > **Proxies** in the left navigation menu. @@ -34,7 +34,7 @@ This guide walks you through creating an App LLM Proxy, optionally attaching gua --- -## Add Guardrails (Optional) +## Add guardrails (optional) You can attach policies and guardrails to your proxy that apply to all requests: @@ -54,7 +54,7 @@ You can attach policies and guardrails to your proxy that apply to all requests: --- -## Deploy Proxy to Gateway +## Deploy proxy to gateway After creating your proxy, you must deploy it to a gateway before it can be used. @@ -95,7 +95,7 @@ Click **Back to App LLM Proxy** to return to the proxy details page. --- -## Get Started +## Get started Once the proxy is deployed, the proxy details page shows the **Get Started** panel on the right. @@ -115,7 +115,7 @@ To call a specific resource, append the resource path: https://{gateway-host}/{proxy-name}/chat/completions ``` -### App LLM Proxy Keys +### App LLM proxy keys Generate an API key to authenticate requests to the deployed gateway. @@ -125,13 +125,13 @@ Generate an API key to authenticate requests to the deployed gateway. !!! danger "Important" API keys are only displayed once. Store it in a secure location immediately — you will not be able to retrieve it again. -### Deployed Gateways +### Deployed gateways The **Deployed Gateways** section lists all gateways this proxy is deployed to, along with the deployment status. --- -## Next Steps +## Next steps - [Invoke via SDKs](../using-sdks.md) - Connect to your proxy from Python using provider-native SDKs - [Manage Your App LLM Proxy](manage-proxy.md) - Configure provider, resources, security, and guardrails diff --git a/en/docs/cloud/ai-workspace/llm-proxies/manage-proxy.md b/en/docs/cloud/ai-workspace/llm-proxies/manage-proxy.md index 4e4ba021..bd972eef 100644 --- a/en/docs/cloud/ai-workspace/llm-proxies/manage-proxy.md +++ b/en/docs/cloud/ai-workspace/llm-proxies/manage-proxy.md @@ -1,4 +1,4 @@ -# Manage App LLM Proxy +# Manage app LLM proxy Once you create an App LLM Proxy, you can manage its configuration through the proxy details page. This guide covers all management operations available for your specialized application or agent proxy. @@ -18,7 +18,7 @@ Once you create an App LLM Proxy, you can manage its configuration through the p --- -## Access Proxy Details +## Access proxy details 1. Navigate to **LLM** > **Proxies** in the left navigation menu. @@ -37,7 +37,7 @@ The **Deploy to Gateway** button and a **delete** icon are located in the top-ri --- -## Provider Settings +## Provider settings
@@ -45,7 +45,7 @@ Configure which LLM service provider the proxy connects to and how it authentica
-### LLM Service Provider +### LLM service provider 1. Go to the **Provider** tab. @@ -56,7 +56,7 @@ Configure which LLM service provider the proxy connects to and how it authentica !!! info Changing the provider updates related settings such as authentication and available resources. -### API Key Configuration +### API key configuration If your selected provider uses API key authentication, you'll see the **API Key Configuration** section below the provider dropdown. @@ -86,7 +86,7 @@ Define which API endpoints (resources) are available through this proxy by impor -### OpenAPI Specification +### OpenAPI specification The OpenAPI specification defines the resources (API endpoints) available through your proxy. Depending on the provider, the specification may be automatically populated. @@ -103,7 +103,7 @@ The OpenAPI specification defines the resources (API endpoints) available throug !!! tip "OpenAPI Format" Supports OpenAPI 3.0 and 3.1 specifications in both JSON and YAML formats. -### View Resources +### View resources After importing, the **Resources** section displays the count and list of parsed resources. Each resource shows: @@ -148,7 +148,7 @@ Attach guardrails to enforce content safety, compliance, and quality standards o -### Global Guardrails +### Global guardrails Global guardrails apply to **all resources** in the proxy. @@ -168,7 +168,7 @@ Global guardrails apply to **all resources** in the proxy. Added guardrails appear as pills showing the guardrail name and version. -### Resource-wise Guardrails +### Resource-wise guardrails Resource-wise guardrails apply to **specific endpoints** only. This section lists each resource from your OpenAPI specification, allowing you to attach guardrails to individual endpoints. @@ -182,7 +182,7 @@ Resource-wise guardrails apply to **specific endpoints** only. This section list 4. Click **Submit** to attach the guardrail to the resource. -### Manage Guardrails +### Manage guardrails - **View**: Global guardrails appear as pills in the Global Guardrails section. Resource-specific guardrails appear under each resource card. - **Remove**: Click the **×** icon on a guardrail pill to remove it. @@ -195,7 +195,7 @@ Resource-wise guardrails apply to **specific endpoints** only. This section list --- -## Save Changes +## Save changes After making configuration changes across any tab (Provider, Resources, Security, Guardrails), click the **Save** button at the bottom-right of the page to persist your changes. @@ -206,7 +206,7 @@ Use the **Cancel** button to discard all unsaved changes and revert to the last --- -## Delete Proxy +## Delete proxy To delete a proxy, click the **delete** icon (trash icon) in the top-right corner of the proxy details page, next to the Deploy to Gateway button. @@ -224,7 +224,7 @@ To delete a proxy, click the **delete** icon (trash icon) in the top-right corne --- -## Next Steps +## Next steps - [Policies Overview](../policies/overview.md) - Learn about all available policies for proxies - [Policy Hub](https://wso2.com/api-platform/policy-hub/) - Browse the full catalog of available guardrails and policies diff --git a/en/docs/cloud/ai-workspace/llm-proxies/overview.md b/en/docs/cloud/ai-workspace/llm-proxies/overview.md index 93847ddc..a24c27cf 100644 --- a/en/docs/cloud/ai-workspace/llm-proxies/overview.md +++ b/en/docs/cloud/ai-workspace/llm-proxies/overview.md @@ -1,12 +1,12 @@ -# App LLM Proxies Overview +# App LLM proxies overview -## Why a Proxy on Top of a Provider? +## Why a proxy on top of a provider? An **LLM Provider** connects the gateway to an upstream LLM service and can be called directly. An **App LLM Proxy** adds an optional, application-facing endpoint on top when you need controls that are specific to a Gen AI application or agent. The main benefit is specialization and isolation. A single provider can be used directly, or it can back multiple App LLM Proxies: one for a customer-facing chatbot with strict guardrails, another for an internal agent with relaxed settings, and another for a workflow-specific Gen AI assistant. Each proxy is independently configured, and swapping the underlying provider doesn't require any changes to the applications or agents calling the proxy. -## What You Can Do with an App LLM Proxy +## What you can do with an app LLM proxy **Expose a controlled API endpoint** The proxy gives you a stable URL your Gen AI application or agent calls. You control which resources (API paths) are exposed, and can enable or disable them without touching the upstream provider. @@ -26,7 +26,7 @@ Create separate proxies for different Gen AI applications, agents, teams, or env **Switch providers without client changes** Because applications and agents call the proxy URL rather than the provider directly, you can swap the underlying LLM Provider (e.g., from OpenAI to Azure OpenAI) without any changes on the client side. -## Next Steps +## Next steps - [Configure App LLM Proxy](configure-proxy.md) — Step-by-step guide to create and deploy your first specialized proxy - [Manage App LLM Proxy](manage-proxy.md) — Update configuration, guardrails, and resources after deployment diff --git a/en/docs/cloud/ai-workspace/mcp-proxies/apply-policies.md b/en/docs/cloud/ai-workspace/mcp-proxies/apply-policies.md index 01be6a20..a35681b3 100644 --- a/en/docs/cloud/ai-workspace/mcp-proxies/apply-policies.md +++ b/en/docs/cloud/ai-workspace/mcp-proxies/apply-policies.md @@ -1,11 +1,11 @@ -# Apply Policies for MCP Proxy +# Apply policies for MCP proxy Once you create an MCP proxy, you can apply various policies through the Policies page. The AI Workspace provides a set of built-in policies that let you govern how traffic flows through your MCP Proxies. These policies are applied at the policy level. However, you have the option to define rules per tools, prompts, etc. inside MCP specific policies if required. This will essentially apply the policies at each capability level. -## Access Control Policies +## Access control policies There are several policies that enforce security for MCP Proxies. @@ -15,7 +15,7 @@ There are several policies that enforce security for MCP Proxies. | [MCP Authorization](https://wso2.com/api-platform/policy-hub/policies/mcp-authz) | Apply fine-grained authorization for MCP capabilities and JSON RPC methods. | | [MCP Access Control](https://wso2.com/api-platform/policy-hub/policies/mcp-acl-list) | Allow or deny access to MCP capabilities. | -## Other Policies +## Other policies | Policy | Description | |-----------|-------------| @@ -23,7 +23,7 @@ There are several policies that enforce security for MCP Proxies. You can apply other standard policies as well to MCP Proxies. Some policies might not be compatible with MCP. Hence the behavior will vary based on the policy. -## Policy Hub +## Policy hub All policies in the AI Workspace are powered by the [Policy Hub](https://wso2.com/api-platform/policy-hub/). The Policy Hub is a central registry of all available policies and their latest versions. diff --git a/en/docs/cloud/ai-workspace/mcp-proxies/configure-proxy.md b/en/docs/cloud/ai-workspace/mcp-proxies/configure-proxy.md index 6083722a..618be283 100644 --- a/en/docs/cloud/ai-workspace/mcp-proxies/configure-proxy.md +++ b/en/docs/cloud/ai-workspace/mcp-proxies/configure-proxy.md @@ -1,4 +1,4 @@ -# Configure an MCP Proxy +# Configure an MCP proxy An MCP Proxy exposes a managed endpoint that your applications use to reach an MCP Server. Once deployed, the proxy handles authentication and various other access controls. @@ -11,7 +11,7 @@ This guide walks you through creating a proxy and deploying it to a gateway. --- -## Create a New Proxy +## Create a new proxy 1. Navigate to **MCP** > **MCP Proxies** in the left navigation menu. @@ -41,7 +41,7 @@ This guide walks you through creating a proxy and deploying it to a gateway. --- -## Deploy Proxy to Gateway +## Deploy proxy to gateway After creating your proxy, you must deploy it to a gateway before it can be used. @@ -82,11 +82,11 @@ Click **Back to MCP Proxy** to return to the proxy details page. --- -## Get Started +## Get started Once the proxy is deployed, you will see the MCP Proxy URL in the overview page. -### Connect with an MCP Client +### Connect with an MCP client Select a gateway from the **Gateways** dropdown to see the base URL for calling this proxy through that gateway. @@ -98,6 +98,6 @@ https://{gateway-host}/{proxy-context}/mcp --- -## Next Steps +## Next steps - [Apply Policies](apply-policies.md) - Apply policies for MCP Proxies. diff --git a/en/docs/cloud/ai-workspace/mcp-proxies/overview.md b/en/docs/cloud/ai-workspace/mcp-proxies/overview.md index 46ab898f..62b63db5 100644 --- a/en/docs/cloud/ai-workspace/mcp-proxies/overview.md +++ b/en/docs/cloud/ai-workspace/mcp-proxies/overview.md @@ -1,6 +1,6 @@ -# MCP Proxies Overview +# MCP proxies overview -## What is Model Context Protocol? +## What is model context protocol? MCP is a JSON-RPC–based protocol designed to standardize how applications interact with large language models (LLMs). It enables sharing of contextual information—such as local files, databases, or APIs—with LLMs, while also allowing applications to expose tools and capabilities for AI-driven workflows and integrations. @@ -8,12 +8,12 @@ MCP follows a host–client–server architecture and supports two primary trans For more information, refer to the official [specification](https://modelcontextprotocol.io/introduction). -## What is an MCP Proxy? +## What is an MCP proxy? An MCP Proxy lets you connect the gateway to an upstream MCP Server. The MCP Clients can connect to the dedicated endpoint provided by the gateway to connect to your upstream MCP Server. The proxy allows you to apply various policies which allow you to control the MCP traffic through the gateway. -## What does an MCP Proxy offer? +## What does an MCP proxy offer? While MCP defines an RPC-based communication model between agents and tools, it does not fully address the complexities of real-world enterprise environments. @@ -23,7 +23,7 @@ While MCP defines an RPC-based communication model between agents and tools, it MCP Proxy will address these challenges providing built-in security, governance, and observability for all MCP communication. -## Next Steps +## Next steps - [Configure MCP Proxy](configure-proxy.md) — Step-by-step guide to create and deploy your first proxy - [Apply Policies](apply-policies.md) — Apply policies after deployment \ No newline at end of file diff --git a/en/docs/cloud/ai-workspace/overview.md b/en/docs/cloud/ai-workspace/overview.md index 1bc44659..62fe0927 100644 --- a/en/docs/cloud/ai-workspace/overview.md +++ b/en/docs/cloud/ai-workspace/overview.md @@ -1,10 +1,10 @@ -# AI Workspace Overview +# AI Workspace overview The AI Workspace is the control plane for AI Gateway runtimes. It gives platform teams a centralized interface to register gateways, configure providers and application-facing proxies, apply policies, and manage deployments without working directly with the Gateway-Controller API. -## What AI Workspace Manages +## What AI Workspace manages -### AI Gateways +### AI gateways Register and manage AI Gateway runtimes that process AI traffic. @@ -14,7 +14,7 @@ Register and manage AI Gateway runtimes that process AI traffic. Learn more in [AI Gateways](ai-gateways/setting-up.md). -### LLM Providers +### LLM providers Define reusable connections to upstream AI services such as OpenAI, Anthropic, Azure OpenAI, Gemini, and Mistral. @@ -24,7 +24,7 @@ Define reusable connections to upstream AI services such as OpenAI, Anthropic, A Learn more in [LLM Providers](llm-providers/overview.md). -### App LLM Proxies +### App LLM proxies Create optional, application-facing endpoints for Gen AI applications and agents when they need controls that differ from the underlying provider. @@ -34,7 +34,7 @@ Create optional, application-facing endpoints for Gen AI applications and agents Learn more in [App LLM Proxies](llm-proxies/overview.md). -### GenAI Applications +### GenAI applications Represent the actual AI applications/Agents in your project and map existing API keys to them for application-level visibility. @@ -44,7 +44,7 @@ Represent the actual AI applications/Agents in your project and map existing API Learn more in [GenAI Applications](genai-applications.md). -### MCP Proxies +### MCP proxies Expose and govern Model Context Protocol servers through connected gateways. @@ -54,7 +54,7 @@ Expose and govern Model Context Protocol servers through connected gateways. Learn more in [MCP Proxies](mcp-proxies/overview.md). -### Policies and Guardrails +### Policies and guardrails Configure AI-specific governance controls for providers and proxies. @@ -64,7 +64,7 @@ Configure AI-specific governance controls for providers and proxies. Learn more in [Policies](policies/overview.md). -## How It Works +## How it works 1. Create an AI Gateway entry in AI Workspace. 2. Start the gateway runtime and register it with the generated token. @@ -79,6 +79,6 @@ AI Workspace is the control plane. The [AI Gateway](../ai-gateway/overview.md) i - Use AI Gateway docs when you want to work directly with the runtime, Gateway-Controller API, or standalone deployment model. - Use AI Workspace docs when you want centralized lifecycle management for connected gateways and their AI assets. -## Getting Started +## Getting started To start using the control plane, follow the [Getting Started](getting-started.md) guide. \ No newline at end of file diff --git a/en/docs/cloud/ai-workspace/policies/guardrails/azure-content-safety.md b/en/docs/cloud/ai-workspace/policies/guardrails/azure-content-safety.md index 4f7e9721..f91903f6 100644 --- a/en/docs/cloud/ai-workspace/policies/guardrails/azure-content-safety.md +++ b/en/docs/cloud/ai-workspace/policies/guardrails/azure-content-safety.md @@ -1,4 +1,4 @@ -# Azure Content Safety Content Moderation +# Azure Content Safety content moderation The Azure Content Safety guardrail integrates with the Azure Content Safety API to filter harmful content in requests and LLM-generated responses. It checks for four categories — hate speech, sexual content, self-harm, and violence — each with a configurable severity threshold. @@ -15,9 +15,9 @@ The Azure Content Safety guardrail integrates with the Azure Content Safety API azurecontentsafety_key = "your-api-key" ``` -## Configuration Parameters +## Configuration parameters -### Advanced Settings +### Advanced settings Content moderation settings are configured independently for the **request** and **response** phases. Both sections have the same parameters: @@ -31,7 +31,7 @@ Content moderation settings are configured independently for the **request** and | **Self Harm Severity Threshold** | `3` | Severity threshold for self-harm content (0–7). Use `-1` to disable. | | **Violence Severity Threshold** | `4` | Severity threshold for violence (0–7). Use `-1` to disable. | -### Severity Scale +### Severity scale | Score | Meaning | |-------|---------| @@ -40,7 +40,7 @@ Content moderation settings are configured independently for the **request** and | 4–5 | Medium severity | | 6–7 | High severity | -## Add This Policy +## Add this policy 1. Navigate to **AI Workspace** > **LLM Providers** or **App LLM Proxies**. 2. Click on the provider or proxy name. diff --git a/en/docs/cloud/ai-workspace/policies/guardrails/overview.md b/en/docs/cloud/ai-workspace/policies/guardrails/overview.md index 8ad0864e..563f560a 100644 --- a/en/docs/cloud/ai-workspace/policies/guardrails/overview.md +++ b/en/docs/cloud/ai-workspace/policies/guardrails/overview.md @@ -1,8 +1,8 @@ -# Guardrails Overview +# Guardrails overview Guardrails inspect and act on the content of requests and responses flowing through the AI Gateway — detecting unsafe content, masking sensitive data, and caching responses. They run without any changes to client applications. -## Available Guardrails +## Available guardrails | Guardrail | Description | |-----------|-------------| @@ -12,7 +12,7 @@ Guardrails inspect and act on the content of requests and responses flowing thro | [Word Count](word-count-guardrail.md) | Enforce minimum or maximum word count limits on prompts or responses. | | [Sentence Count](sentence-count-guardrail.md) | Enforce minimum or maximum sentence count limits on prompts or responses. | -## How Guardrails Work +## How guardrails work | Guardrail | Behavior | |-----------|----------| @@ -22,7 +22,7 @@ Guardrails inspect and act on the content of requests and responses flowing thro | **Word Count** | Blocks requests or responses with `422 Unprocessable Entity` if the word count falls outside the configured limits. | | **Sentence Count** | Blocks requests or responses with `422 Unprocessable Entity` if the sentence count falls outside the configured limits. | -## Applying Guardrails +## Applying guardrails Guardrails can be configured on both LLM Providers and App LLM Proxies: @@ -35,7 +35,7 @@ Guardrails can be configured on both LLM Providers and App LLM Proxies: When guardrails are configured at multiple levels, all of them are evaluated. Provider-level guardrails run first, followed by proxy-level guardrails. -### How to Add a Guardrail +### How to add a guardrail **On an LLM Provider:** @@ -61,7 +61,7 @@ When guardrails are configured at multiple levels, all of them are evaluated. Pr 8. Click **Submit**. 9. Save the proxy configuration and redeploy as needed. -## Guardrail Intervention Response +## Guardrail intervention response When a guardrail blocks a request or response, it returns the following structure: @@ -78,6 +78,6 @@ When a guardrail blocks a request or response, it returns the following structur } ``` -## Learn More +## Learn more The [Policy Hub](https://wso2.com/api-platform/policy-hub/) is the central registry for all guardrail policies. It contains full documentation, configuration schemas, and the latest versions of each guardrail. diff --git a/en/docs/cloud/ai-workspace/policies/guardrails/regex-pii-masking.md b/en/docs/cloud/ai-workspace/policies/guardrails/regex-pii-masking.md index fee8ddfc..f042df2b 100644 --- a/en/docs/cloud/ai-workspace/policies/guardrails/regex-pii-masking.md +++ b/en/docs/cloud/ai-workspace/policies/guardrails/regex-pii-masking.md @@ -1,4 +1,4 @@ -# PII Masking Regex +# PII masking regex The PII Masking Regex guardrail detects and masks Personally Identifiable Information (PII) in request and response payloads using regex patterns. It supports built-in detectors for common PII types and custom regex patterns for additional entities. @@ -7,7 +7,7 @@ It operates in two modes: - **Masking (default)** — Detected PII is replaced with a reversible placeholder (e.g., `[EMAIL_0000]`). The original value can be restored in the response flow. - **Redaction** — Detected PII is permanently replaced with `*****` and cannot be restored. -## Configuration Parameters +## Configuration parameters All parameters are optional. @@ -20,7 +20,7 @@ All parameters are optional. | **JSON Path** | `$.messages` | JSONPath to extract the field to scan. If empty, the entire payload is processed as plain text. | | **Redact PII** | `false` | When `true`, matched PII is permanently replaced with `*****`. When `false`, PII is masked with reversible placeholders. | -## Add This Policy +## Add this policy 1. Navigate to **AI Workspace** > **LLM Providers** or **App LLM Proxies**. 2. Click on the provider or proxy name. diff --git a/en/docs/cloud/ai-workspace/policies/guardrails/semantic-prompt-guard.md b/en/docs/cloud/ai-workspace/policies/guardrails/semantic-prompt-guard.md index c035515e..2a984bdb 100644 --- a/en/docs/cloud/ai-workspace/policies/guardrails/semantic-prompt-guard.md +++ b/en/docs/cloud/ai-workspace/policies/guardrails/semantic-prompt-guard.md @@ -1,4 +1,4 @@ -# Semantic Prompt Guard +# Semantic prompt guard The Semantic Prompt Guard uses vector embeddings and cosine similarity to match incoming prompts against lists of **allowed** and **denied** phrases. Unlike pattern-based guardrails, it understands semantic meaning — it can block prompts that are *similar in meaning* to a denied phrase, even if they use completely different words. @@ -7,7 +7,7 @@ The Semantic Prompt Guard uses vector embeddings and cosine similarity to match See [Gateway Configuration](#gateway-configuration) below for the required `config.toml` settings. -## How It Works +## How it works When a request arrives, the guardrail: @@ -16,7 +16,7 @@ When a request arrives, the guardrail: 3. **If allowed phrases are configured** — blocks the request if no allowed phrase is similar enough (below the allow threshold). 4. **If denied phrases are configured** — blocks the request if any denied phrase is similar enough (above the deny threshold). -## Configuration Parameters +## Configuration parameters All parameters are optional and available under **Advanced Settings**. @@ -29,7 +29,7 @@ All parameters are optional and available under **Advanced Settings**. | **Denied Phrases** | — | Phrases that represent unacceptable prompts. If set, any prompt semantically similar to a denied phrase is blocked. | | **Show Assessment** | `false` | When `true`, the intervention response includes the matched phrase and similarity score. | -## Gateway Configuration +## Gateway configuration The embedding provider is configured in the gateway's `config.toml` file. These settings apply to all policies that use embeddings. @@ -41,7 +41,7 @@ embedding_provider_dimension = 1536 embedding_provider_api_key = "" ``` -### Supported Embedding Providers +### Supported embedding providers | Provider | `embedding_provider` value | Example endpoint | Example model | |----------|---------------------------|-----------------|---------------| @@ -49,7 +49,7 @@ embedding_provider_api_key = "" | Mistral AI | `MISTRAL` | `https://api.mistral.ai/v1/embeddings` | `mistral-embed` | | Azure OpenAI | `AZURE_OPENAI` | Your Azure OpenAI endpoint URL | Deployment name is in the URL | -## Add This Guardrail +## Add this guardrail 1. Configure the embedding provider in `config.toml` and restart the gateway. 2. Navigate to **AI Workspace** > **LLM Providers** or **App LLM Proxies**. @@ -61,7 +61,7 @@ embedding_provider_api_key = "" 8. Click **Add** (for providers) or **Submit** (for proxies). 9. Deploy the provider or proxy to apply the changes. -## Example: Block Off-Topic Prompts +## Example: Block off-topic prompts The following configuration uses an allow list to ensure only coding-related prompts are forwarded to the LLM. @@ -99,7 +99,7 @@ The following configuration uses an allow list to ensure only coding-related pro } ``` -## Choosing Similarity Thresholds +## Choosing similarity thresholds | Threshold | Effect | |-----------|--------| diff --git a/en/docs/cloud/ai-workspace/policies/guardrails/sentence-count-guardrail.md b/en/docs/cloud/ai-workspace/policies/guardrails/sentence-count-guardrail.md index 7ee86247..787da24a 100644 --- a/en/docs/cloud/ai-workspace/policies/guardrails/sentence-count-guardrail.md +++ b/en/docs/cloud/ai-workspace/policies/guardrails/sentence-count-guardrail.md @@ -1,4 +1,4 @@ -# Sentence Count Guardrail +# Sentence count guardrail The Sentence Count Guardrail validates the number of sentences in a request or response. Use it to enforce policies on the structural complexity of prompts or responses — for example, requiring responses to be at least a certain length, or capping how many sentences a user prompt can contain. @@ -6,7 +6,7 @@ The Sentence Count Guardrail validates the number of sentences in a request or r All parameters are under **Advanced Settings**. Configure a **request** section, a **response** section, or both. -### Request / Response Parameters +### Request / response parameters Each section (request and response) has the following parameters: @@ -18,7 +18,7 @@ Each section (request and response) has the following parameters: | **invert** | No | `false` | When `true`, the guardrail intervenes when the sentence count **is within** the configured range instead of outside it. | | **showAssessment** | No | `false` | When `true`, the intervention response includes details about the violation. | -## Add This Guardrail +## Add this guardrail 1. Navigate to **AI Workspace** > **LLM Providers** or **App LLM Proxies**. 2. Click on the provider or proxy name. @@ -28,7 +28,7 @@ Each section (request and response) has the following parameters: 6. Click **Add** (for providers) or **Submit** (for proxies). 7. Deploy the provider or proxy to apply the changes. -## Example: Limit Prompt to 3 Sentences +## Example: Limit prompt to 3 sentences The following configuration blocks requests where the user message contains more than 3 sentences. diff --git a/en/docs/cloud/ai-workspace/policies/guardrails/word-count-guardrail.md b/en/docs/cloud/ai-workspace/policies/guardrails/word-count-guardrail.md index 407afb66..976cc44f 100644 --- a/en/docs/cloud/ai-workspace/policies/guardrails/word-count-guardrail.md +++ b/en/docs/cloud/ai-workspace/policies/guardrails/word-count-guardrail.md @@ -1,4 +1,4 @@ -# Word Count Guardrail +# Word count guardrail The Word Count Guardrail validates the number of words in a request or response. Use it to enforce content length policies — for example, limiting how long a user's prompt can be, or ensuring responses meet a minimum length requirement. @@ -6,7 +6,7 @@ The Word Count Guardrail validates the number of words in a request or response. All parameters are under **Advanced Settings**. Configure a **request** section, a **response** section, or both. -### Request / Response Parameters +### Request / response parameters Each section (request and response) has the following parameters: @@ -18,7 +18,7 @@ Each section (request and response) has the following parameters: | **invert** | No | `false` | When `true`, the guardrail intervenes when the word count **is within** the configured range instead of outside it. | | **showAssessment** | No | `false` | When `true`, the intervention response includes details about the violation. | -## Add This Guardrail +## Add this guardrail 1. Navigate to **AI Workspace** > **LLM Providers** or **App LLM Proxies**. 2. Click on the provider or proxy name. @@ -28,7 +28,7 @@ Each section (request and response) has the following parameters: 6. Click **Add** (for providers) or **Submit** (for proxies). 7. Deploy the provider or proxy to apply the changes. -## Example: Limit Prompt Length +## Example: Limit prompt length The following configuration blocks requests where the user message exceeds 50 words. diff --git a/en/docs/cloud/ai-workspace/policies/other-policies/basic-rate-limit.md b/en/docs/cloud/ai-workspace/policies/other-policies/basic-rate-limit.md index 940087c0..b12f60cf 100644 --- a/en/docs/cloud/ai-workspace/policies/other-policies/basic-rate-limit.md +++ b/en/docs/cloud/ai-workspace/policies/other-policies/basic-rate-limit.md @@ -1,11 +1,11 @@ -# Rate Limit - Basic +# Rate limit - basic The Rate Limit - Basic policy enforces a simple request count limit on an LLM Provider or Proxy. Use it to cap the total number of requests allowed within a time window, regardless of token consumption. !!! info "Built-in Rate Limiting vs. Rate Limit - Basic Policy" The AI Workspace also has a first-class **Rate Limiting** tab on LLM Providers that provides request count and token count limits on the Backend scope (Per Consumer coming soon). The Rate Limit - Basic policy is a lightweight alternative that can be attached through the Guardrails interface when you need a simple per-route request cap. -## Configuration Parameters +## Configuration parameters | Parameter | Required | Description | |-----------|----------|-------------| @@ -13,7 +13,7 @@ The Rate Limit - Basic policy enforces a simple request count limit on an LLM Pr | **Limits[].Count** | Yes | The maximum number of requests allowed within the duration. | | **Limits[].Duration** | Yes | The time window for the limit (e.g., `60s`, `1m`, `1h`). | -## Add This Policy +## Add this policy 1. Navigate to **AI Workspace** > **LLM Providers** or **App LLM Proxies**. 2. Click on the provider or proxy name. diff --git a/en/docs/cloud/ai-workspace/policies/other-policies/model-round-robin.md b/en/docs/cloud/ai-workspace/policies/other-policies/model-round-robin.md index 2447a7f6..91747f25 100644 --- a/en/docs/cloud/ai-workspace/policies/other-policies/model-round-robin.md +++ b/en/docs/cloud/ai-workspace/policies/other-policies/model-round-robin.md @@ -1,15 +1,15 @@ -# Model Round Robin +# Model round robin The Model Round Robin policy distributes requests across multiple AI models using round-robin selection. If a model returns a server error (`5xx`) or a rate limit response (`429`), it can be temporarily suspended so that traffic automatically shifts to the remaining healthy models. -## Configuration Parameters +## Configuration parameters | Parameter | Required | Description | |-----------|----------|-------------| | **Models** | Yes | The list of model names to balance across (e.g., `gpt-4o`, `gpt-4-turbo`). Add at least two models. | | **Suspend Duration** | No | Number of seconds to suspend a model after it returns a `5xx` or `429` response. While suspended, the model is skipped. Set to `0` (default) to disable suspension. | -## Add This Policy +## Add this policy 1. Navigate to **AI Workspace** > **LLM Providers** or **App LLM Proxies**. 2. Click on the provider or proxy name. diff --git a/en/docs/cloud/ai-workspace/policies/other-policies/prompt-decorator.md b/en/docs/cloud/ai-workspace/policies/other-policies/prompt-decorator.md index 6fdd0f6a..ee6ab349 100644 --- a/en/docs/cloud/ai-workspace/policies/other-policies/prompt-decorator.md +++ b/en/docs/cloud/ai-workspace/policies/other-policies/prompt-decorator.md @@ -1,8 +1,8 @@ -# Prompt Decorator +# Prompt decorator The Prompt Decorator policy prepends or appends content to prompts before they are sent to the upstream LLM. Use it to inject system instructions, safety guidelines, or contextual information into every request — without requiring changes to the client application. -## Configuration Parameters +## Configuration parameters | Parameter | Required | Default | Description | |-----------|----------|---------|-------------| @@ -10,7 +10,7 @@ The Prompt Decorator policy prepends or appends content to prompts before they a | **JSON Path** | Yes | — | A JSONPath expression pointing to the field in the request body where the decoration is applied (e.g., `$.messages` for a chat array, `$.prompt` for a text field). | | **Append** | No | `false` | When `true`, the decoration is appended after the existing content. When `false` (default), it is prepended before. | -### Decoration Formats +### Decoration formats **Text decoration** — Use a plain string to inject text into a single-field prompt: @@ -29,7 +29,7 @@ The Prompt Decorator policy prepends or appends content to prompts before they a ] ``` -## Add This Policy +## Add this policy 1. Navigate to **AI Workspace** > **LLM Providers** or **App LLM Proxies**. 2. Click on the provider or proxy name. @@ -41,7 +41,7 @@ The Prompt Decorator policy prepends or appends content to prompts before they a 8. Click **Add** (for providers) or **Submit** (for proxies). 9. Deploy the provider or proxy to apply the changes. -## Example: Inject a System Prompt +## Example: Inject a system prompt The following configuration prepends a system instruction to every chat completion request: diff --git a/en/docs/cloud/ai-workspace/policies/other-policies/prompt-template.md b/en/docs/cloud/ai-workspace/policies/other-policies/prompt-template.md index d25a575e..c37cf3c6 100644 --- a/en/docs/cloud/ai-workspace/policies/other-policies/prompt-template.md +++ b/en/docs/cloud/ai-workspace/policies/other-policies/prompt-template.md @@ -1,14 +1,14 @@ -# Prompt Template +# Prompt template The Prompt Template policy applies reusable, parameterized prompt templates to requests. Instead of sending a raw prompt, clients send a template reference (`template://?param=value`) and the gateway substitutes the parameters into the configured template before forwarding the request to the LLM. -## Configuration Parameters +## Configuration parameters | Parameter | Required | Description | |-----------|----------|-------------| | **Templates** | Yes | A list of named templates. Each template has a **name** (identifier) and a **prompt** string containing placeholders in the format `[[parameter-name]]`. | -### Template Placeholder Syntax +### Template placeholder syntax Use `[[parameter-name]]` inside the prompt string to mark substitution points: @@ -18,7 +18,7 @@ Translate the following text from [[from]] to [[to]]: [[text]] When a client calls `template://translate?from=English&to=Spanish&text=Hello`, the policy replaces each placeholder with the corresponding query parameter value. -## Advanced Settings +## Advanced settings | Parameter | Default | Description | |-----------|---------|-------------| @@ -26,7 +26,7 @@ When a client calls `template://translate?from=English&to=Spanish&text=Hello`, t | **On Missing Template** | `error` | Behavior when a referenced template name is not found. `error` returns an immediate error response; `passthrough` leaves the original template reference unchanged. | | **On Unresolved Placeholder** | `keep` | Behavior when a placeholder has no matching query parameter. `keep` leaves the placeholder as-is; `empty` replaces it with an empty string; `error` returns an immediate error response. | -## Add This Policy +## Add this policy 1. Navigate to **AI Workspace** > **LLM Providers** or **App LLM Proxies**. 2. Click on the provider or proxy name. @@ -37,7 +37,7 @@ When a client calls `template://translate?from=English&to=Spanish&text=Hello`, t 7. Click **Add** (for providers) or **Submit** (for proxies). 8. Deploy the provider or proxy to apply the changes. -## Example: Translation Template +## Example: Translation template **Configured template:** diff --git a/en/docs/cloud/ai-workspace/policies/other-policies/semantic-cache.md b/en/docs/cloud/ai-workspace/policies/other-policies/semantic-cache.md index fd1c313e..89824ec0 100644 --- a/en/docs/cloud/ai-workspace/policies/other-policies/semantic-cache.md +++ b/en/docs/cloud/ai-workspace/policies/other-policies/semantic-cache.md @@ -1,4 +1,4 @@ -# Semantic Cache +# Semantic cache The Semantic Cache policy caches LLM responses and serves them for semantically similar future requests — without calling the upstream LLM. Unlike exact-match caching, it uses vector embeddings and cosine similarity to recognize requests that ask essentially the same question with different wording. @@ -7,7 +7,7 @@ The Semantic Cache policy caches LLM responses and serves them for semantically See [Gateway Configuration](#gateway-configuration) below for the required `config.toml` settings. -## How It Works +## How it works 1. An incoming request arrives. The policy extracts the relevant text (full payload or a JSONPath-specified field). 2. The embedding provider converts the text into a vector. @@ -17,7 +17,7 @@ The Semantic Cache policy caches LLM responses and serves them for semantically If the embedding service or vector database is unreachable, the policy fails open — the request proceeds to the upstream LLM as normal. -## Configuration Parameters +## Configuration parameters These are the parameters configurable from the policy UI when adding the guardrail: @@ -26,7 +26,7 @@ These are the parameters configurable from the policy UI when adding the guardra | **Similarity Threshold** | Yes | Cosine similarity score (0.0–1.0) above which a cached response is returned. Recommended starting value: `0.85`. | | **JSON Path** | No | A JSONPath expression to extract the text to embed from the request body (e.g., `$.messages[0].content`). If not set, the entire request payload is embedded. | -## Gateway Configuration +## Gateway configuration The embedding provider and vector database are configured in the gateway's `config.toml` file. These settings apply as defaults to all Semantic Cache policy instances. @@ -46,7 +46,7 @@ vector_db_provider_password = "default" vector_db_provider_ttl = 3600 ``` -### Supported Embedding Providers +### Supported embedding providers | Provider | `embedding_provider` value | Example endpoint | Dimension | |----------|---------------------------|-----------------|-----------| @@ -54,14 +54,14 @@ vector_db_provider_ttl = 3600 | Mistral AI | `MISTRAL` | `https://api.mistral.ai/v1/embeddings` | `1024` (`mistral-embed`) | | Azure OpenAI | `AZURE_OPENAI` | Your Azure OpenAI endpoint URL | Depends on deployment | -### Supported Vector Databases +### Supported vector databases | Provider | `vector_db_provider` value | Notes | |----------|---------------------------|-------| | Redis | `REDIS` | Requires [Redis Search](https://redis.io/docs/latest/develop/ai/search-and-query/) module | | Milvus | `MILVUS` | Better suited for large-scale deployments (>1M vectors) | -## Add This Policy +## Add this policy 1. Configure the embedding provider and vector database in `config.toml` and restart the gateway. 2. Navigate to **AI Workspace** > **LLM Providers** or **App LLM Proxies**. @@ -73,7 +73,7 @@ vector_db_provider_ttl = 3600 8. Click **Add** (for providers) or **Submit** (for proxies). 9. Deploy the provider or proxy to apply the changes. -## Choosing a Similarity Threshold +## Choosing a similarity threshold | Threshold | Effect | |-----------|--------| @@ -84,7 +84,7 @@ vector_db_provider_ttl = 3600 Start at `0.85` and adjust based on observed cache hit rates and response relevance. -## Performance Notes +## Performance notes - Embedding generation adds approximately 100–500ms to each request. This is typically offset by the 1–5 second savings on cache hits. - Redis (with RediSearch) is suited for smaller datasets (under 1M cached vectors). Milvus is optimized for larger-scale deployments. diff --git a/en/docs/cloud/ai-workspace/policies/other-policies/token-based-rate-limit.md b/en/docs/cloud/ai-workspace/policies/other-policies/token-based-rate-limit.md index 8f7a26d7..ac62cec4 100644 --- a/en/docs/cloud/ai-workspace/policies/other-policies/token-based-rate-limit.md +++ b/en/docs/cloud/ai-workspace/policies/other-policies/token-based-rate-limit.md @@ -1,4 +1,4 @@ -# Token-Based Rate Limiting +# Token-based rate limiting AI services bill on a per-token basis, so uncontrolled usage can lead to unexpected costs. The AI Workspace provides two ways to apply token-based rate limits: @@ -9,7 +9,7 @@ AI services bill on a per-token basis, so uncontrolled usage can lead to unexpec --- -## Built-in Rate Limiting +## Built-in rate limiting Configured through the **Rate Limiting** tab on an LLM Provider. Supports limiting by request count and token count. @@ -23,7 +23,7 @@ Configured through the **Rate Limiting** tab on an LLM Provider. Supports limiti !!! info "Per Consumer Rate Limiting — Coming Soon" Only the **Backend** scope is currently configurable. -### Configuration Modes +### Configuration modes - **Provider-wide** — A single limit across all API endpoints. - **Per Resource** — Individual limits per API endpoint. @@ -31,7 +31,7 @@ Configured through the **Rate Limiting** tab on an LLM Provider. Supports limiti !!! note Provider-wide and Per Resource modes are mutually exclusive. Clear existing limits before switching. -### Limit Criteria +### Limit criteria | Criterion | Description | |-----------|-------------| @@ -52,11 +52,11 @@ For each criterion, set a **Quota** and a **Reset Duration** (`second`, `minute` --- -## Token Based Rate Limit Policy +## Token based rate limit policy A policy attached via the **Guardrails** tab. Tracks prompt tokens, completion tokens, and total tokens separately — giving finer control than the built-in Rate Limiting tab. Can be applied to both LLM Providers and App LLM Proxies. -### Configuration Parameters +### Configuration parameters Configure limits for any combination of the three token categories. At least one must be specified. @@ -67,7 +67,7 @@ Configure limits for any combination of the three token categories. At least one | **Total Token Count** | Conditional | Maximum combined prompt + completion tokens within the duration. | | **Duration** | Yes | Time window for the limit (e.g., `60s`, `1m`, `1h`). | -### Add This Policy +### Add this policy 1. Navigate to **AI Workspace** > **LLM Providers** or **App LLM Proxies**. 2. Click on the provider or proxy name and go to the **Guardrails** tab. diff --git a/en/docs/cloud/ai-workspace/policies/overview.md b/en/docs/cloud/ai-workspace/policies/overview.md index f546495f..69e82616 100644 --- a/en/docs/cloud/ai-workspace/policies/overview.md +++ b/en/docs/cloud/ai-workspace/policies/overview.md @@ -1,4 +1,4 @@ -# Policies Overview +# Policies overview The AI Workspace provides built-in policies that let you govern how traffic flows through your LLM Providers and App LLM Proxies. Policies can be applied at the provider level (affecting all proxies that use the provider) or at the proxy level (scoped to a specific proxy or individual endpoints). @@ -14,7 +14,7 @@ Guardrails enforce content safety and compliance on requests and responses. | [Word Count](guardrails/word-count-guardrail.md) | Enforce word count limits on prompts or responses. | | [Sentence Count](guardrails/sentence-count-guardrail.md) | Enforce sentence count limits on prompts or responses. | -## Rate Limit +## Rate limit Rate limit policies control how much LLM traffic — by token count or monetary cost — can flow through a provider or proxy. @@ -24,7 +24,7 @@ Rate limit policies control how much LLM traffic — by token count or monetary | [Token-Based Rate Limit](rate-limit/token-based-rate-limit.md) | Limit prompt, completion, or total token consumption within a time window. | | [LLM Cost-Based Rate Limit](rate-limit/llm-cost-based-rate-limit.md) | Enforce monetary spending budgets (e.g., $10/hour). Requires the LLM Cost policy. | -## Other Policies +## Other policies | Policy | Description | |--------|-------------| @@ -36,7 +36,7 @@ Rate limit policies control how much LLM traffic — by token count or monetary | [Semantic Cache](other-policies/semantic-cache.md) | Cache LLM responses and serve them for semantically similar requests. | -## Where Policies are Applied +## Where policies are applied Policies are configured through the management tabs of your LLM Providers and App LLM Proxies: @@ -45,13 +45,13 @@ Policies are configured through the management tabs of your LLM Providers and Ap When both provider-level and proxy-level policies are active, they are both enforced. Provider-level policies act as a baseline, and proxy-level policies add additional protection. -## Policy Hub +## Policy hub All guardrail policies in the AI Workspace are powered by the [Policy Hub](https://wso2.com/api-platform/policy-hub/). The Policy Hub is a central registry of all available policies and their latest versions. Visit the [Policy Hub](https://wso2.com/api-platform/policy-hub/) to explore all available guardrails, their documentation, and configuration schemas. -## Next Steps +## Next steps - [Guardrails Overview](guardrails/overview.md) — Explore available guardrails and how to configure them - [Writing an AI Policy](writing-an-ai-policy.md) — Learn how to write a custom AI policy for the self-hosted gateway diff --git a/en/docs/cloud/ai-workspace/policies/rate-limit/llm-cost-based-rate-limit.md b/en/docs/cloud/ai-workspace/policies/rate-limit/llm-cost-based-rate-limit.md index eb67a82f..fb20ccac 100644 --- a/en/docs/cloud/ai-workspace/policies/rate-limit/llm-cost-based-rate-limit.md +++ b/en/docs/cloud/ai-workspace/policies/rate-limit/llm-cost-based-rate-limit.md @@ -1,11 +1,11 @@ -# LLM Cost-Based Rate Limit +# LLM Cost-based rate limit The LLM Cost-Based Rate Limit policy enforces monetary spending limits on LLM traffic. It reads the cost of each API call calculated by the [LLM Cost](llm-cost.md) policy and blocks requests once a configured budget is exceeded within a time window. !!! info "Prerequisites" The **LLM Cost** policy must be added to the same provider or proxy **after** this policy in the policy list. The gateway evaluates response-phase policies in reverse order, so the cost is calculated before the budget is checked. Without the LLM Cost, no cost data is available and budget enforcement is skipped. -## Configuration Parameters +## Configuration parameters | Parameter | Required | Description | |-----------|----------|-------------| @@ -15,7 +15,7 @@ The LLM Cost-Based Rate Limit policy enforces monetary spending limits on LLM tr When multiple budget limits are configured, all of them are enforced — the most restrictive active limit applies. -## Add This Policy +## Add this policy 1. Add this policy first, then add the **LLM Cost** policy after it in the policy list. 2. Navigate to **AI Workspace** > **LLM Providers** or **App LLM Proxies**. @@ -41,7 +41,7 @@ When multiple budget limits are configured, all of them are enforced — the mos | `x-ratelimit-cost-limit-dollars` | Budget limit in USD (e.g., `10.000000`) | | `x-ratelimit-cost-remaining-dollars` | Remaining budget in USD (e.g., `7.432100`) | -## Example: $10/hour and $100/day Budget +## Example: $10/hour and $100/day budget The following configuration enforces two simultaneous spending limits. Both must be satisfied for requests to proceed — once either limit is reached, requests are blocked until that window resets. diff --git a/en/docs/cloud/ai-workspace/policies/rate-limit/llm-cost.md b/en/docs/cloud/ai-workspace/policies/rate-limit/llm-cost.md index 4d4e0914..f30c2f20 100644 --- a/en/docs/cloud/ai-workspace/policies/rate-limit/llm-cost.md +++ b/en/docs/cloud/ai-workspace/policies/rate-limit/llm-cost.md @@ -1,11 +1,11 @@ -# LLM Cost +# LLM cost The LLM Cost policy calculates the monetary cost of each LLM API call and makes the result available to other policies — primarily [LLM Cost-Based Rate Limit](llm-cost-based-rate-limit.md). It runs in the response phase, requires no user configuration, and never exposes the cost to the caller. !!! info "Required for cost-based rate limiting" Add this policy to the same provider or proxy as **LLM Cost-Based Rate Limit**, and place it **after** it in the policy list. The gateway evaluates response-phase policies in reverse order, so the cost is calculated before the budget is checked. -## How It Works +## How it works 1. When the LLM response arrives (including streaming/SSE responses), the policy reads the model name from the response body. 2. It looks up the model in the built-in pricing database. @@ -14,7 +14,7 @@ The LLM Cost policy calculates the monetary cost of each LLM API call and makes The cost is internal — it is never forwarded to the caller. -## Supported Providers +## Supported providers | Provider | Notes | |----------|-------| @@ -23,11 +23,11 @@ The cost is internal — it is never forwarded to the caller. | **Google Gemini** | Google AI Studio and Vertex AI, including multi-modal (audio, image), web search grounding, and thinking models | | **Mistral** | All Mistral models including audio duration-based billing (Voxtral) | -## Configuration Parameters +## Configuration parameters This policy has no user-configurable parameters. The pricing database path is a gateway-level system setting configured in `config.toml`. -## Add This Policy +## Add this policy 1. Navigate to **AI Workspace** > **LLM Providers** or **App LLM Proxies**. 2. Click on the provider or proxy name. @@ -44,7 +44,7 @@ This policy has no user-configurable parameters. The pricing database path is a - If the model is not found in the pricing database, cost is set to `0`, a warning is logged, and the request is not blocked. - The pricing database is bundled with the gateway image and loaded at startup. A gateway restart is required to pick up pricing file updates. -## Metadata Written +## Metadata written | Key | Value | |-----|-------| diff --git a/en/docs/cloud/ai-workspace/policies/rate-limit/token-based-rate-limit.md b/en/docs/cloud/ai-workspace/policies/rate-limit/token-based-rate-limit.md index fcd21a65..958d7ffe 100644 --- a/en/docs/cloud/ai-workspace/policies/rate-limit/token-based-rate-limit.md +++ b/en/docs/cloud/ai-workspace/policies/rate-limit/token-based-rate-limit.md @@ -1,8 +1,8 @@ -# Token-Based Rate Limit +# Token-based rate limit The Token-Based Rate Limit policy enforces rate limits based on token consumption rather than request count. Limits can be applied to prompt (input) tokens, completion (output) tokens, or total tokens — independently or in combination. -## Configuration Parameters +## Configuration parameters At least one of the three limit categories must be configured. Any combination is valid. @@ -21,7 +21,7 @@ Each entry within a category requires: When multiple limits are configured within a category, the most restrictive limit is enforced. -## Add This Policy +## Add this policy 1. Navigate to **AI Workspace** > **LLM Providers** or **App LLM Proxies**. 2. Click on the provider or proxy name. @@ -45,7 +45,7 @@ When multiple limits are configured within a category, the most restrictive limi | `X-RateLimit-Reset` | Time (epoch seconds) when the window resets | | `RateLimit-*` | IETF equivalents of the above | -## Example: Cap Total Tokens Per Minute +## Example: Cap total tokens per minute Block requests once 100,000 total tokens have been consumed in a 1-minute window. @@ -54,7 +54,7 @@ Block requests once 100,000 total tokens have been consumed in a 1-minute window | Total Token Limits — count | `100000` | | Total Token Limits — duration | `1m` | -## Example: Separate Prompt and Completion Limits +## Example: Separate prompt and completion limits Limit prompt tokens to 50,000 per hour and completion tokens to 20,000 per hour independently. diff --git a/en/docs/cloud/ai-workspace/policies/writing-an-ai-policy.md b/en/docs/cloud/ai-workspace/policies/writing-an-ai-policy.md index 1383e647..33a6a91d 100644 --- a/en/docs/cloud/ai-workspace/policies/writing-an-ai-policy.md +++ b/en/docs/cloud/ai-workspace/policies/writing-an-ai-policy.md @@ -1,4 +1,4 @@ -# Writing an AI Policy for the Self-Hosted Gateway +# Writing an AI policy for the Self-hosted gateway AI policies allow you to inspect, control, and modify traffic going to and from Large Language Models (LLMs), such as OpenAI, Anthropic, or other providers. @@ -9,7 +9,7 @@ The key difference is how you handle LLM request and response bodies, especially - JSON responses - Streaming responses (SSE) -## Key Idea +## Key idea LLM responses come in two formats: @@ -20,7 +20,7 @@ LLM responses come in two formats: Your policy must be implemented to handle **both formats**. -## Which Interfaces to Implement +## Which interfaces to implement Choose based on what your policy needs to do: @@ -31,7 +31,7 @@ Choose based on what your policy needs to do: | Inspect or modify buffered (in-memory) response | `ResponsePolicy` | `ResponseBodyMode: BodyModeBuffer` | | Inspect or modify streaming response | `StreamingResponsePolicy` (embeds `ResponsePolicy`) | `ResponseBodyMode: BodyModeStream` | -## Recommended Pattern +## Recommended pattern For most AI policies, implement both: @@ -41,7 +41,7 @@ For most AI policies, implement both: !!! tip The gateway automatically chooses which handler to call. `OnResponseBodyChunk` is invoked only if the entire policy chain is streaming-compatible. If any policy in the chain does not support streaming, `OnResponseBody` is used as a fallback. -## Minimal AI Policy Example +## Minimal AI policy example ```go package myaipolicy @@ -98,12 +98,12 @@ func (p *MyAIPolicy) OnResponseBody( } ``` -## Best Practices +## Best practices - **Always handle both streaming and non-streaming** - The gateway may fall back to buffered mode if any policy in the chain does not support streaming. - **Use Metadata to share state** - Pass data between request and response phases using the `Metadata` map. - **Implement streaming + fallback for compatibility** - Ensure your policy works correctly regardless of whether the chain runs in streaming or buffered mode. -## Learn More +## Learn more - [Writing a Custom Policy for the Self-Hosted Gateway](../../api-platform-gateway/writing-a-custom-policy.md) diff --git a/en/docs/cloud/ai-workspace/using-sdks.md b/en/docs/cloud/ai-workspace/using-sdks.md index b84b203d..be8e6d28 100644 --- a/en/docs/cloud/ai-workspace/using-sdks.md +++ b/en/docs/cloud/ai-workspace/using-sdks.md @@ -1,4 +1,4 @@ -# Invoke Providers and Proxies via SDKs +# Invoke providers and proxies via SDKs Once you have deployed an LLM Provider or App LLM Proxy in the AI Workspace, you can invoke it using any supported AI SDK by pointing it at the gateway's Invoke URL and authenticating with your generated API key. @@ -461,7 +461,7 @@ Mistral exposes both a native SDK and an OpenAI-compatible API at `/v1`. print(chunk.content, end="", flush=True) ``` -## Azure AI Foundry +## Azure AI foundry !!! note The `model` / `azure_deployment` parameter must be your **Azure deployment name**. diff --git a/en/docs/cloud/api-monetization/getting-started.md b/en/docs/cloud/api-monetization/getting-started.md index f0bfe845..0a62487f 100644 --- a/en/docs/cloud/api-monetization/getting-started.md +++ b/en/docs/cloud/api-monetization/getting-started.md @@ -1,4 +1,4 @@ -# Getting Started with API Monetization +# Getting started with API monetization To enable API monetization, you need to connect your Stripe account to API Platform. Once connected, API Platform creates Stripe products, prices, customers, and subscriptions on your behalf, and reports usage to Stripe for billing. @@ -17,7 +17,7 @@ Before you begin, ensure you have: - A **Standard secret key**, which has full access to your Stripe account, or - A **Restricted secret key**, which scopes access to only the permissions you grant. If you choose this option, make sure the key is granted the permissions listed below. - ??? info "Permissions for Restricted Secret Keys" + ??? info "Permissions for restricted secret keys" Grant the following minimum permissions when creating the restricted secret key in the Stripe Dashboard: @@ -48,7 +48,7 @@ Before you begin, ensure you have: --- -## Add Stripe Credentials +## Add Stripe credentials 1. Sign in to the [API Platform Console](https://console.bijira.dev/). 2. In the API Platform Console header, go to the **Organization** list and select your organization. @@ -60,8 +60,8 @@ Before you begin, ensure you have: 6. Click **Add Stripe Credentials**. 7. Enter the following details: - - **Secret Key:** The secret key from your Stripe account. - - **Publishable Key:** The publishable key from your Stripe account. + - **Secret key:** The secret key from your Stripe account. + - **Publishable key:** The publishable key from your Stripe account. 8. Click **Save**. @@ -69,6 +69,6 @@ Once saved, API Platform is connected to your Stripe account and you can start m --- -## Next Steps +## Next steps - [Manage Paid Subscription Plans](manage-paid-subscription-plans.md) diff --git a/en/docs/cloud/api-monetization/manage-paid-subscription-plans.md b/en/docs/cloud/api-monetization/manage-paid-subscription-plans.md index 4ee68862..52a2df70 100644 --- a/en/docs/cloud/api-monetization/manage-paid-subscription-plans.md +++ b/en/docs/cloud/api-monetization/manage-paid-subscription-plans.md @@ -1,4 +1,4 @@ -# Manage Paid Subscription Plans +# Manage paid subscription plans Paid subscription plans allow organizations to monetize their APIs by charging API consumers based on usage or access. API Platform supports multiple pricing models, enabling you to tailor plans to different business requirements. Once created, you can assign these plans to specific APIs. @@ -13,7 +13,7 @@ Before you begin, ensure you have: --- -## Pricing Models +## Pricing models API Platform supports the following pricing models for paid subscription plans. @@ -30,7 +30,7 @@ API Platform supports the following pricing models for paid subscription plans. --- -## Step 1: Create a Paid Subscription Plan +## Step 1: Create a paid subscription plan 1. Sign in to the [API Platform Console](https://console.bijira.dev/). 2. In the API Platform Console header, go to the **Organization** list and select your organization. @@ -43,7 +43,7 @@ API Platform supports the following pricing models for paid subscription plans. 6. In the **Create Subscription Plan** pane, enter the plan details: - **Name** and **Description** for the plan. The name is unique and cannot be changed after creation. - - **Rate Limiting:** Set the **Request Count** (must be greater than 0) and the **Request Count Time Unit** (Minute, Hour, or Day). Enable **Burst Control** to protect your backend from sudden request spikes — the burst limit is enforced over a shorter time unit than the one you selected. + - **Rate limiting:** Set the **Request Count** (must be greater than 0) and the **Request Count Time Unit** (Minute, Hour, or Day). Enable **Burst Control** to protect your backend from sudden request spikes — the burst limit is enforced over a shorter time unit than the one you selected. - **Pricing:** Select a **Pricing Model** (Free, Flat, Unit, Volume, or Graduated), **Currency**, **Billing Period**, and the price amount. ![Create Subscription Plan form showing Name, Description, Rate Limiting section with request count and time unit, and Pricing section with Per Unit model and USD monthly billing](../../assets/img/api-monetization/add-paid-plan-form.png){ width="800" } @@ -57,7 +57,7 @@ The paid subscription plan is now created and listed under **Subscription Plans* --- -## Step 2: Assign Paid Plans to an API +## Step 2: Assign paid plans to an API Once you have created paid subscription plans, you can enable them for specific APIs. This allows API consumers to discover and subscribe to paid plans through the Developer Portal. diff --git a/en/docs/cloud/api-monetization/overview.md b/en/docs/cloud/api-monetization/overview.md index 90cc6154..5d03528a 100644 --- a/en/docs/cloud/api-monetization/overview.md +++ b/en/docs/cloud/api-monetization/overview.md @@ -1,23 +1,23 @@ -# API Monetization +# API monetization -## What is API Monetization? +## What is API monetization? API monetization allows organizations to generate revenue from their APIs by offering paid subscription plans to API consumers. By integrating with Stripe as a payment provider, API Platform enables organizations to define flexible pricing models and manage billing for API usage directly from the console. -## API Monetization Overview +## API monetization overview With API monetization in API Platform, organizations can seamlessly monetize their APIs by creating paid subscription plans with various pricing models. This allows you to: - **Integrate with Stripe:** Connect your Stripe account to API Platform to handle payments and billing securely. -- **Define Flexible Pricing Models:** Create subscription plans using pricing models such as Free, Flat, Unit, Volume, and Graduated to match different business needs. -- **Enable Monetization Per API:** Choose which APIs offer paid plans, giving you granular control over your monetization strategy. -- **Manage Subscriptions:** API consumers can discover and subscribe to paid plans via the Developer Portal, streamlining the purchasing experience. +- **Define flexible pricing models:** Create subscription plans using pricing models such as Free, Flat, Unit, Volume, and Graduated to match different business needs. +- **Enable monetization per API:** Choose which APIs offer paid plans, giving you granular control over your monetization strategy. +- **Manage subscriptions:** API consumers can discover and subscribe to paid plans via the Developer Portal, streamlining the purchasing experience. By monetizing APIs through API Platform, organizations gain a streamlined way to offer tiered access, manage billing, and grow API-driven revenue. -## Getting Started +## Getting started 1. **Configure Stripe:** Add your Stripe credentials at the organization level to enable payment processing. -2. **Create Paid Subscription Plans:** Define subscription plans with the appropriate pricing model for your APIs. -3. **Enable Plans for APIs:** Assign paid subscription plans to specific APIs to make them available for consumers. -4. **Consumer Subscription:** API consumers discover and subscribe to paid plans through the Developer Portal. +2. **Create paid subscription plans:** Define subscription plans with the appropriate pricing model for your APIs. +3. **Enable plans for APIs:** Assign paid subscription plans to specific APIs to make them available for consumers. +4. **Consumer subscription:** API consumers discover and subscribe to paid plans through the Developer Portal. diff --git a/en/docs/cloud/api-monetization/subscribe-to-paid-plan.md b/en/docs/cloud/api-monetization/subscribe-to-paid-plan.md index 9722f3d7..8c40489a 100644 --- a/en/docs/cloud/api-monetization/subscribe-to-paid-plan.md +++ b/en/docs/cloud/api-monetization/subscribe-to-paid-plan.md @@ -1,4 +1,4 @@ -# Subscribe to a Paid Plan +# Subscribe to a paid plan API consumers can browse monetized APIs on the Developer Portal and subscribe to a paid subscription plan using a secure Stripe-powered checkout. Once the payment is successful, the application is subscribed to the API and can be used to invoke it. @@ -13,7 +13,7 @@ Before you begin, ensure you have: --- -## Subscribe to an API with a Paid Plan +## Subscribe to an API with a paid plan 1. Go to the [API Platform Developer Portal](https://devportal.bijira.dev/) and sign in to your organization. 2. In the Developer Portal sidebar, click **APIs** to open the API listing page. @@ -43,6 +43,6 @@ After subscribing, generate application keys and invoke the API using the creden --- -## Next Steps +## Next steps - [View Billing and Usage](view-billing-and-usage.md) diff --git a/en/docs/cloud/api-monetization/view-billing-and-usage.md b/en/docs/cloud/api-monetization/view-billing-and-usage.md index cbbccee3..bedb2f19 100644 --- a/en/docs/cloud/api-monetization/view-billing-and-usage.md +++ b/en/docs/cloud/api-monetization/view-billing-and-usage.md @@ -1,10 +1,10 @@ -# View Billing and Usage +# View billing and usage The Developer Portal provides a consolidated **Billing & Usage** view where API consumers can monitor usage, review invoices, and manage their paid subscriptions across all subscribed APIs. --- -## Access the Billing Page +## Access the billing page 1. Go to the [API Platform Developer Portal](https://devportal.bijira.dev/) and sign in to your organization. 2. Click your profile icon in the top right corner. @@ -14,7 +14,7 @@ The Developer Portal provides a consolidated **Billing & Usage** view where API --- -## Usage Summary +## Usage summary The **Usage Summary** tab displays an **API Usage Overview** for a selected period (e.g., Current Month). This includes: @@ -39,7 +39,7 @@ Invoices are generated and issued by Stripe based on your subscription's billing --- -## Billed Subscriptions +## Billed subscriptions The **Billed Subscriptions** tab shows all paid subscriptions associated with your account. For each subscription you can see the API, application, plan, billing cycle, amount, next billing date, and status. Use the **Filter by Status** dropdown to narrow the list, and click **Manage** to update or cancel a subscription. diff --git a/en/docs/cloud/api-platform-gateway/analytics.md b/en/docs/cloud/api-platform-gateway/analytics.md index 77352420..84f82140 100644 --- a/en/docs/cloud/api-platform-gateway/analytics.md +++ b/en/docs/cloud/api-platform-gateway/analytics.md @@ -6,7 +6,7 @@ This guide explains how to monitor and analyze API traffic for your Self-Hosted API Platform provides comprehensive analytics for your Self-Hosted Gateway, giving you visibility into API usage, performance, and errors. Analytics data is collected from your gateway and displayed in the API Platform Console. -## Viewing Analytics +## Viewing analytics To view analytics for your Self-Hosted Gateway: @@ -15,11 +15,11 @@ To view analytics for your Self-Hosted Gateway: 3. In the left navigation, go to **Insights** and select **API Insights**. 4. Select the environment associated with your Self-Hosted Gateway. -## Analytics Dashboard +## Analytics dashboard The analytics dashboard provides key metrics: -### Traffic Metrics +### Traffic metrics | Metric | Description | |--------|-------------| @@ -28,7 +28,7 @@ The analytics dashboard provides key metrics: | **Unique Consumers** | Number of unique API consumers | | **Top APIs** | Most frequently called APIs | -### Performance Metrics +### Performance metrics | Metric | Description | |--------|-------------| @@ -37,7 +37,7 @@ The analytics dashboard provides key metrics: | **P99 Latency** | 99th percentile response time | | **Backend Time** | Time spent waiting for backend responses | -### Error Metrics +### Error metrics | Metric | Description | |--------|-------------| @@ -46,7 +46,7 @@ The analytics dashboard provides key metrics: | **5xx Errors** | Server error count | | **Error Breakdown** | Errors by type and API | -## Filtering Analytics Data +## Filtering analytics data You can filter analytics data by: @@ -56,11 +56,11 @@ You can filter analytics data by: - **Application**: Specific consumer application - **Status Code**: Success or error responses -## Real-Time Monitoring +## Real-time monitoring For real-time monitoring of your gateway: -### Gateway Health +### Gateway health Check the gateway health endpoint: @@ -81,7 +81,7 @@ Expected response: } ``` -### Live Traffic Logs +### Live traffic logs View live traffic logs: @@ -110,7 +110,7 @@ MOESIF_KEY=your-moesif-application-id For detailed instructions, see [Integrate API Platform with Moesif](../monitoring-and-insights/integrate-bijira-with-moesif.md). -### Moesif Features +### Moesif features With Moesif integration, you get: @@ -119,7 +119,7 @@ With Moesif integration, you get: - **Alerting**: Get notified of anomalies and issues - **Monetization**: Bill customers based on API usage -## Exporting Analytics Data +## Exporting analytics data To export analytics data: @@ -130,7 +130,7 @@ To export analytics data: - **CSV**: For spreadsheet analysis - **JSON**: For programmatic processing -## Setting Up Alerts +## Setting up alerts Configure alerts to get notified of issues: @@ -142,7 +142,7 @@ Configure alerts to get notified of issues: - **Notification**: Email, Slack, or webhook 4. Click **Save**. -### Example Alert Configurations +### Example alert configurations **High Error Rate Alert:** ```yaml @@ -162,7 +162,7 @@ duration: 3 minutes notification: email ``` -## Gateway Metrics Endpoint +## Gateway metrics endpoint The Self-Hosted Gateway exposes a Prometheus-compatible metrics endpoint: @@ -170,7 +170,7 @@ The Self-Hosted Gateway exposes a Prometheus-compatible metrics endpoint: curl http://localhost:9091/metrics ``` -### Available Metrics +### Available metrics | Metric | Type | Description | |--------|------|-------------| @@ -202,9 +202,9 @@ Import the API Platform Gateway dashboard in Grafana: 3. Select your Prometheus data source. 4. Click **Import**. -## Troubleshooting Analytics +## Troubleshooting analytics -### No Data Appearing +### No data appearing If analytics data isn't appearing: @@ -212,7 +212,7 @@ If analytics data isn't appearing: 2. **Review logs**: Look for analytics-related errors in gateway logs. 3. **Wait for aggregation**: Data may take a few minutes to appear. -### Incomplete Data +### Incomplete data If data appears incomplete: @@ -220,7 +220,7 @@ If data appears incomplete: 2. **Verify filters**: Remove filters to see all data. 3. **Check gateway uptime**: Data gaps may indicate gateway restarts. -## What's Next? +## What's next? - [Managing Policies](manage-policies.md): Configure policies for your APIs - [Troubleshooting](troubleshooting.md): Common issues and solutions diff --git a/en/docs/cloud/api-platform-gateway/apply-custom-policies-to-apis.md b/en/docs/cloud/api-platform-gateway/apply-custom-policies-to-apis.md index eff30dd5..c219def4 100644 --- a/en/docs/cloud/api-platform-gateway/apply-custom-policies-to-apis.md +++ b/en/docs/cloud/api-platform-gateway/apply-custom-policies-to-apis.md @@ -1,8 +1,8 @@ -# Apply Custom Policies to APIs +# Apply custom policies to APIs After [building the gateway with your custom policies](build-gateway-with-custom-policies.md) and starting it, the gateway automatically sends its policy manifest to the control plane on connection. You can then sync your custom policies to the organization and apply them to your APIs. -## Step 1: View the Gateway Policies +## Step 1: View the gateway policies 1. Sign in to [API Platform Console](https://console.bijira.dev). 2. Go to **Organization Level** in API Platform. @@ -25,7 +25,7 @@ The console fetches the manifest from the gateway and displays a table of all po ![Policy list with Custom type showing Sync button in the Sync Status column](../../assets/img/api-platform-gateway/gateway/sync-option.png) -## Step 2: Sync the Custom Policy to the Organization +## Step 2: Sync the custom policy to the organization Custom policies must be synced to the organization before they can be applied to APIs. @@ -47,7 +47,7 @@ Once synced, the custom policy is available organization-wide and can be applied - Patch version updates are not supported. - Version downgrades are not allowed. -## Step 3: View Organization-Level Custom Policies +## Step 3: View organization-level custom policies After syncing, the custom policy appears in the **Custom Policies** section on the main Gateways page. To view it: @@ -68,7 +68,7 @@ This section lists all custom policies available in the organization with the fo !!! note To delete a synced custom policy, none of the APIs in the organization should be using it. -## Step 4: Apply the Custom Policy to an API +## Step 4: Apply the custom policy to an API After syncing, the custom policy appears in the policy list when configuring an API proxy. To apply it: @@ -79,7 +79,7 @@ After syncing, the custom policy appears in the policy list when configuring an For detailed instructions on attaching and configuring policies on an API, see [Adding and Managing Policies](manage-policies.md). -## What's Next? +## What's next? - [Publish APIs Overview](publish-apis/overview.md): Learn about publishing APIs on the self-hosted gateway - [Subscription Based APIs](publish-apis/subscription-based-apis.md): Publish APIs with subscription-based access control diff --git a/en/docs/cloud/api-platform-gateway/architecture.md b/en/docs/cloud/api-platform-gateway/architecture.md index ee069460..f64869e6 100644 --- a/en/docs/cloud/api-platform-gateway/architecture.md +++ b/en/docs/cloud/api-platform-gateway/architecture.md @@ -1,14 +1,14 @@ -# Self-Hosted Gateway Architecture +# Self-hosted gateway architecture The self-hosted gateway runs in a customer-managed private data plane while connecting to the API Platform Control Plane hosted in the cloud. This architecture allows organizations to manage APIs centrally while keeping API traffic, runtime execution, and backend connectivity within their own environment. -## Cloud Control Plane +## Cloud control plane The **API Platform Control Plane** is hosted in the cloud and provides centralized API management capabilities. It is used to configure, publish, and manage APIs and policies. The self-hosted gateway establishes an outbound WebSocket connection to the cloud control plane over **port 443**. This connection is used to receive API and policy configuration updates from the control plane. Since the connection is initiated from the private data plane, customers do not need to expose internal gateway management services to the public internet. -## Private Data Plane +## Private data plane The **Private Data Plane** runs within the customer’s infrastructure. It handles API traffic, applies runtime policies, and communicates with backend services. API requests from consumers are processed entirely within this private environment. @@ -16,7 +16,7 @@ The **Private Data Plane** runs within the customer’s infrastructure. It handl The Gateway includes the following components: -### Gateway Controller +### Gateway controller The Gateway Controller is responsible for receiving API and policy configurations from the cloud control plane and configuring the gateway runtime accordingly. @@ -28,20 +28,20 @@ It contains the following services: | Controller XDS | Provides runtime configuration to the gateway router using xDS. | | Database | Stores gateway configuration and runtime metadata required by the controller. | -#### Gateway Controller Ports +#### Gateway controller ports | Port | Type | Description | | ----- | ----- | ----- | | 9090 | External | Controller REST API port. | | 9002 | Internal | Controller admin port. | -### Gateway Runtime +### Gateway runtime The Gateway Runtime is responsible for handling API traffic. It includes the router and the policy engine. The router receives incoming API requests over HTTP or HTTPS and routes them to the relevant backend services. During request and response processing, the router communicates with the policy engine to execute configured policies such as authentication, authorization, rate limiting, transformation, analytics, or custom policies. -#### Gateway Runtime Ports +#### Gateway runtime ports | Port | Type | Description | | ----- | ----- | ----- | @@ -49,18 +49,18 @@ The router receives incoming API requests over HTTP or HTTPS and routes them to | 8443 | External | HTTPS ingress port for API traffic. | | 9901 | Internal | Envoy admin port. | -## Configuration Flow +## Configuration flow When an API or policy is created or updated in the cloud control plane, the configuration is sent to the Gateway Controller through the outbound WebSocket connection. The Gateway Controller stores the configuration and converts it into runtime configuration required by the Gateway Runtime. The Controller XDS service then configures the router. Once configured, the Gateway Runtime starts serving API traffic according to the policies and routing rules defined in the control plane. -## Runtime Traffic Flow +## Runtime traffic flow API consumers send requests to the Gateway Runtime through the exposed HTTP or HTTPS ingress ports. The router receives the request and identifies the matching API route. It then applies the configured policy chain using the policy engine. After successful policy execution, the request is forwarded to the backend service. Responses from the backend follow the same path back through the gateway, allowing response policies to be applied before the response is returned to the client. -## Key Benefits +## Key benefits This architecture provides centralized API management while keeping runtime execution close to backend services. It helps organizations maintain control over API traffic, reduce exposure of internal systems, and apply consistent policies across APIs managed through the cloud control plane. \ No newline at end of file diff --git a/en/docs/cloud/api-platform-gateway/build-gateway-with-custom-policies.md b/en/docs/cloud/api-platform-gateway/build-gateway-with-custom-policies.md index 455abb65..a706de16 100644 --- a/en/docs/cloud/api-platform-gateway/build-gateway-with-custom-policies.md +++ b/en/docs/cloud/api-platform-gateway/build-gateway-with-custom-policies.md @@ -1,6 +1,6 @@ -# Building the Gateway with Custom Policies +# Building the gateway with custom policies -## Install the AP CLI Tool +## Install the AP CLI tool The `ap` CLI tool is used to build a custom gateway image with your own policies. Download the binary for your platform from the [AP CLI releases page](https://github.com/wso2/api-platform/releases/tag/ap%2Fv0.7.0) and follow the steps below to install it. @@ -76,7 +76,7 @@ The `ap` CLI tool is used to build a custom gateway image with your own policies ap --version ``` -## Configure the Build File +## Configure the build file The `build.yaml` file is already included in the unzipped gateway package. It declares the gateway version and the list of policies to include. Edit this file to add your custom policies before building the gateway image. @@ -103,7 +103,7 @@ Each policy entry uses one of two source types: | `gomodule` | Go module reference for policy hub managed policies (e.g., `github.com/wso2/gateway-controllers/policies/cors@v1`) | | `filePath` | Relative path from `build.yaml` to a local custom policy directory | -### Adding a Custom Policy +### Adding a custom policy Your custom policy can reside anywhere on the filesystem. Use a relative path from the `build.yaml` file to point to it. @@ -128,7 +128,7 @@ policies: !!! note The path in `filePath` is always relative to the location of `build.yaml`, not the directory from which you run the `ap` command. -## Build the Gateway Image +## Build the gateway image Once `build.yaml` is ready, run the following command from the directory containing `build.yaml` to build the custom gateway image: @@ -148,7 +148,7 @@ Once the build completes, the output lists the two image names produced. For exa A `build-manifest.yaml` file is also written alongside `build.yaml`, recording the resolved versions of all policies included in the build. -## Update the Docker Compose File +## Update the Docker compose file After building, update the `image:` fields in your `docker-compose.yaml` to use the newly built images. @@ -172,6 +172,6 @@ Once updated, start the gateway as usual: docker compose --env-file configs/keys.env up ``` -## What's Next? +## What's next? - [Apply Custom Policies to APIs](apply-custom-policies-to-apis.md): Sync your custom policy to the organization and apply it to APIs diff --git a/en/docs/cloud/api-platform-gateway/cloud-gateway.md b/en/docs/cloud/api-platform-gateway/cloud-gateway.md index 114128a9..8606b0f7 100644 --- a/en/docs/cloud/api-platform-gateway/cloud-gateway.md +++ b/en/docs/cloud/api-platform-gateway/cloud-gateway.md @@ -1,4 +1,4 @@ -# API Platform Cloud Gateway +# API Platform Cloud gateway API Platform Cloud Gateway is a fully managed, WSO2-hosted API gateway that provides instant API deployment with zero infrastructure management. @@ -6,7 +6,7 @@ API Platform Cloud Gateway is a fully managed, WSO2-hosted API gateway that prov The API Platform Cloud Gateway is the default gateway available in your organization. When you deploy an API proxy, it's automatically routed through the cloud gateway without any additional setup or configuration required. -## Key Features +## Key features | Feature | Description | |---------|-------------| @@ -17,7 +17,7 @@ The API Platform Cloud Gateway is the default gateway available in your organiza | **Global Reach** | Available across multiple cloud regions | | **Instant Deployment** | APIs are live within seconds of deployment | -## How It Works +## How it works ``` ┌─────────────────────────────────────────────────────────────────┐ @@ -45,7 +45,7 @@ The API Platform Cloud Gateway is the default gateway available in your organiza (publicly accessible) ``` -## When to Use API Platform Cloud Gateway +## When to use API Platform Cloud gateway The API Platform Cloud Gateway is ideal for: @@ -64,7 +64,7 @@ Consider using a [Self-Hosted Gateway](getting-started.md) instead if you requir - **Network isolation**: Running the gateway within your secure network perimeter - **Custom compliance**: Meeting specific regulatory requirements (HIPAA, PCI-DSS, etc.) -## Getting Started +## Getting started The API Platform Cloud Gateway is available by default. To deploy an API: @@ -88,7 +88,7 @@ For example: https://acme-corp.gateway.bijira.dev/orders/v1 ``` -## Included Capabilities +## Included capabilities All features of the API Platform platform are available with the Cloud Gateway: @@ -98,7 +98,7 @@ All features of the API Platform platform are available with the Cloud Gateway: - **Monitoring**: Real-time logs and monitoring - **Security**: OAuth2, API keys, and other authentication methods -## What's Next? +## What's next? - [Self-Hosted Gateway](getting-started.md): Deploy a gateway in your own environment - [Third-Party Gateways](../federation/overview.md): Federate external gateways like AWS API Gateway diff --git a/en/docs/cloud/api-platform-gateway/getting-started.md b/en/docs/cloud/api-platform-gateway/getting-started.md index dc7581f6..684409a3 100644 --- a/en/docs/cloud/api-platform-gateway/getting-started.md +++ b/en/docs/cloud/api-platform-gateway/getting-started.md @@ -1,5 +1,5 @@ --- -title: "Getting Started with Self-Hosted Gateway" +title: "Getting started with Self-hosted gateway" description: "Set up an API Platform Self-Hosted Gateway in your own infrastructure and connect it to the API Platform Cloud control plane." canonical_url: https://wso2.com/api-platform/docs/cloud/api-platform-gateway/getting-started/ md_url: https://wso2.com/api-platform/docs/cloud/api-platform-gateway/getting-started.md @@ -12,7 +12,7 @@ last_updated: 2026-06-11 content_type: "quickstart" --- -# Getting Started with Self-Hosted Gateway +# Getting started with Self-hosted gateway This guide walks you through setting up an API Platform Self-Hosted Gateway in your environment. Follow these quick steps to get your gateway running and connected to API Platform's control plane. @@ -33,7 +33,7 @@ Before you begin, ensure you have: - **Docker** installed and running (for Quick Start) - **Docker Compose** installed -## Create a Self-Hosted Gateway in API Platform Console +## Create a Self-hosted gateway in API Platform console 1. Sign in to [API Platform Console](https://console.bijira.dev). 2. Go to **Organization Level** in API Platform. @@ -54,7 +54,7 @@ Before you begin, ensure you have: 7. Click **Add** and you will be navigated to the Gateway View Page. -## Setup Gateway +## Setup gateway 1. Next, download, set up, and start the gateway on your machine by following the steps in the **Quick Start** section or the detailed instructions below (Steps 1–4). @@ -111,14 +111,14 @@ Before you begin, ensure you have: The gateway should show as **Active** in the API Platform Console under **Gateways**. -## Add API and Invoke +## Add API and invoke !!! note This feature is currently available only for **REST API** proxies that are created from **scratch**, by **importing from OpenAPI**, or by specifying an **endpoint**. This feature is not currently available for **REST API** proxies created by importing an API contract from **GitHub**, or for **WebSocket**, **GraphQL**, **MCP**, or **Egress** APIs. -### Step 1: Create an API Proxy. +### Step 1: Create an API proxy. In this guide, you will specify a URL to an OpenAPI definition of a sample API to create an API proxy. @@ -154,7 +154,7 @@ In this guide, you will specify a URL to an OpenAPI definition of a sample API t ![Reading List API Local overview page showing HTTP Self Hosted Gateway badge, Created lifecycle status, and /books API endpoints list](../../assets/img/api-platform-gateway/gateway/api-overview.png) -### Step 2: Deploy the API Proxy (Optional) +### Step 2: Deploy the API proxy (optional) !!! note This step is **optional** at this stage, as the API is deployed to the gateway by default. However, if you make any changes to the API, you must redeploy it. @@ -167,7 +167,7 @@ In this guide, you will specify a URL to an OpenAPI definition of a sample API t 2. Click **Deploy**. -## Test the API Proxy +## Test the API proxy 1. Navigate to the **Test --> cURL** page of the API Proxy. @@ -175,14 +175,14 @@ In this guide, you will specify a URL to an OpenAPI definition of a sample API t 2. Use the **cURL** for relevant resource to test the API Proxy. -## Next Steps +## Next steps Your Self-Hosted Gateway is now running! Here's what to do next: - **Configure Policies**: Apply policies through the [Adding and Managing Policies](manage-policies.md) guide - **Monitor**: View gateway health and metrics using [Analytics](analytics.md) -## Alternative Deployment Options +## Alternative deployment options For production environments or specific infrastructure requirements, see the detailed configuration guide: diff --git a/en/docs/cloud/api-platform-gateway/high-availability.md b/en/docs/cloud/api-platform-gateway/high-availability.md index 4b7e4b48..b6e9782e 100644 --- a/en/docs/cloud/api-platform-gateway/high-availability.md +++ b/en/docs/cloud/api-platform-gateway/high-availability.md @@ -1,4 +1,4 @@ -## High Availability Deployment with Multiple Gateway Controllers and Runtimes +## High availability deployment with multiple gateway controllers and runtimes The self-hosted gateway can be deployed in a highly available manner by running multiple **Gateway Controller** replicas and multiple **Gateway Runtime** replicas across different network zones or environments. @@ -8,7 +8,7 @@ This ensures that all Gateway Controller replicas operate with a consistent depl ![High-availability setup example](../../assets/img/api-platform-gateway/gateway/high-availability-architecture.png) -## Architecture Overview +## Architecture overview The deployment consists of the following main components: @@ -18,7 +18,7 @@ The deployment consists of the following main components: | **PostgreSQL Database** | Acts as the shared source of truth for API metadata, deployment state, and gateway configuration. | | **Gateway Runtime** | Receives configuration from its connected Gateway Controller and enforces API gateway policies at runtime. | -## Deployment Synchronization Flow +## Deployment synchronization flow When an API deployment request is received, it is handled by one of the available Gateway Controller replicas. @@ -30,7 +30,7 @@ Each Gateway Runtime then applies the received configuration and starts serving Each Gateway Controller replica can manage one or more Gateway Runtime replicas. -## High Availability Behavior +## High availability behavior High availability is achieved by removing dependency on a single controller instance. @@ -40,7 +40,7 @@ If one Gateway Controller replica becomes unavailable, another replica can conti Similarly, multiple Gateway Runtime replicas can be deployed in each environment to ensure API traffic continues to be served even if one runtime replica becomes unavailable. -## Configuration Synchronization +## Configuration synchronization The PostgreSQL database is the central synchronization point between Gateway Controller replicas. It maintains the latest API deployment state and allows all controller replicas to operate consistently. diff --git a/en/docs/cloud/api-platform-gateway/manage-policies.md b/en/docs/cloud/api-platform-gateway/manage-policies.md index ba60a315..26493a8f 100644 --- a/en/docs/cloud/api-platform-gateway/manage-policies.md +++ b/en/docs/cloud/api-platform-gateway/manage-policies.md @@ -1,4 +1,4 @@ -# Adding and Managing Policies +# Adding and managing policies This guide explains how to add and manage policies for your Self-Hosted Gateway using API Platform's unified control plane. @@ -6,7 +6,7 @@ This guide explains how to add and manage policies for your Self-Hosted Gateway Policies allow you to enforce security, rate limiting, transformation, and other governance requirements on your APIs. With the Self-Hosted Gateway, you manage policies centrally through API Platform's Policy Hub, and they are automatically synchronized to your gateway. -## Adding Policies to an API +## Adding policies to an API To add policies to an API deployed on your Self-Hosted Gateway: @@ -33,11 +33,11 @@ To add policies to an API deployed on your Self-Hosted Gateway: 9. Then **Save** the API. 10. Deploy the API changes to the Gateway. -## Available Policy Types +## Available policy types Navigate to [API Platform Policy Hub](https://wso2.com/api-platform/policy-hub/) to discover available policies. -## What's Next? +## What's next? - [Writing a Custom Policy](writing-a-custom-policy.md): Learn how to build a custom policy using the gateway SDK - [Writing an AI Policy](../ai-workspace/policies/writing-an-ai-policy.md): Learn how to write policies for LLM traffic diff --git a/en/docs/cloud/api-platform-gateway/overview.md b/en/docs/cloud/api-platform-gateway/overview.md index 01f308ca..9639cc70 100644 --- a/en/docs/cloud/api-platform-gateway/overview.md +++ b/en/docs/cloud/api-platform-gateway/overview.md @@ -1,10 +1,10 @@ -# API Platform Gateway Overview +# API Platform gateway overview API Platform provides two types of API Platform gateways powered by WSO2, giving you flexibility to choose the deployment model that best fits your requirements. Both gateway types are managed through API Platform's unified control plane, ensuring consistent API management, policy enforcement, and monitoring across all your environments. -## Gateway Types +## Gateway types -### API Platform Cloud Gateway (SaaS) +### API Platform Cloud gateway (SaaS) The API Platform Cloud Gateway is a fully managed, WSO2-hosted gateway that requires zero infrastructure management on your part. @@ -23,7 +23,7 @@ The API Platform Cloud Gateway is a fully managed, WSO2-hosted gateway that requ - Projects where time-to-market is critical - Workloads without strict data residency requirements -### Self-Hosted Gateway +### Self-hosted gateway The Self-Hosted Gateway is a containerized instance of the API Platform Gateway that you deploy and manage in your own infrastructure—on-premises, in a private cloud, or in any public cloud provider. @@ -85,7 +85,7 @@ Both gateway types connect to API Platform's unified control plane: └───────────────────────────┘ ``` -## Common Features +## Common features Both gateway types share these capabilities through the unified control plane: @@ -98,9 +98,9 @@ Both gateway types share these capabilities through the unified control plane: | **Analytics** | Unified API analytics and insights | | **Developer Portal** | Expose APIs to developers through the portal | -## Getting Started +## Getting started -### Using API Platform Cloud Gateway +### Using API Platform Cloud gateway The API Platform Cloud Gateway is available by default in your organization. Simply deploy your APIs and they will be routed through the managed gateway. @@ -110,7 +110,7 @@ The API Platform Cloud Gateway is available by default in your organization. Sim For more details, see [API Platform Cloud Gateway](cloud-gateway.md). -### Using Self-Hosted Gateway +### Using Self-hosted gateway To deploy a Self-Hosted Gateway in your environment: @@ -119,7 +119,7 @@ To deploy a Self-Hosted Gateway in your environment: 3. **[Adding and Managing Policies](manage-policies.md)**: Configure and enforce policies. 4. **[Analytics](analytics.md)**: Monitor API traffic and performance. -## What's Next? +## What's next? - [Getting Started](getting-started.md): Quick start guide for Self-Hosted Gateway - [Setting Up](setting-up.md): Configure for VM, Docker, or Kubernetes diff --git a/en/docs/cloud/api-platform-gateway/publish-apis/lifecycle-management.md b/en/docs/cloud/api-platform-gateway/publish-apis/lifecycle-management.md index 81d2e94f..6f8d2a07 100644 --- a/en/docs/cloud/api-platform-gateway/publish-apis/lifecycle-management.md +++ b/en/docs/cloud/api-platform-gateway/publish-apis/lifecycle-management.md @@ -1,10 +1,10 @@ -# Lifecycle Management +# Lifecycle management API lifecycle management is an important aspect of API management. The API lifecycle consists of various states that an API passes through, from creation to retirement. In API Platform, there are five distinct lifecycle states: created, pre-released, published, deprecated, and retired. By leveraging the various lifecycle states, API managers can optimize the development process and ensure that subscribers have access to the latest and most reliable APIs. -## API Lifecycle States +## API lifecycle states The following lifecycle states are applicable to APIs in API Platform: @@ -16,7 +16,7 @@ The following lifecycle states are applicable to APIs in API Platform: | **DEPRECATED** | The old version of an API is moved to this state when a newer version of the API is PUBLISHED.| The API is deployed and is available to existing subscribers. New subscriptions are disabled. Existing subscribers can continue to use it as usual until the API is retired.| | **RETIRED** | The API is no longer in use when it is in this state.| The API is unpublished and deleted from the Developer Portal.| -## Manage the Lifecycle of an API +## Manage the lifecycle of an API To change the lifecycle state of an API via the API Platform Console, follow the instructions given below: diff --git a/en/docs/cloud/api-platform-gateway/publish-apis/overview.md b/en/docs/cloud/api-platform-gateway/publish-apis/overview.md index 66488b4e..51251c0e 100644 --- a/en/docs/cloud/api-platform-gateway/publish-apis/overview.md +++ b/en/docs/cloud/api-platform-gateway/publish-apis/overview.md @@ -1,4 +1,4 @@ -# Publish APIs on a Self-Hosted Gateway +# Publish APIs on a Self-hosted gateway After you create and deploy an API proxy to a **Self-Hosted Gateway**, you can make consumers aware of it by moving the API through the lifecycle and publishing it. Publishing updates the API lifecycle to **Published** so it can appear in the API Platform Developer Portal and be invoked according to how access is configured. diff --git a/en/docs/cloud/api-platform-gateway/publish-apis/subscription-based-apis.md b/en/docs/cloud/api-platform-gateway/publish-apis/subscription-based-apis.md index 531a64d2..aa27d267 100644 --- a/en/docs/cloud/api-platform-gateway/publish-apis/subscription-based-apis.md +++ b/en/docs/cloud/api-platform-gateway/publish-apis/subscription-based-apis.md @@ -20,7 +20,7 @@ This model fits APIs where you need tiered access, usage limits, or clear commer For detailed steps and field behavior, see [Assign Subscription Plans to APIs](../../develop-api-proxy/subscription-plans.md). -## Assign Subscription Validation Policy to the API +## Assign subscription validation policy to the API 1. Go to **Develop** → **Policies**. diff --git a/en/docs/cloud/api-platform-gateway/setting-up.md b/en/docs/cloud/api-platform-gateway/setting-up.md index 8bac3c8d..3f1808d4 100644 --- a/en/docs/cloud/api-platform-gateway/setting-up.md +++ b/en/docs/cloud/api-platform-gateway/setting-up.md @@ -1,11 +1,11 @@ -# Setting Up +# Setting up This guide provides detailed instructions for deploying the API Platform Self-Hosted Gateway in production environments. Choose the infrastructure option that matches your environment. !!! tip "Quick Start" If you're just getting started, see the [Getting Started](getting-started.md) guide for a quick setup. -## Setup Instructions +## Setup instructions === "Virtual Machine" @@ -215,7 +215,7 @@ This guide provides detailed instructions for deploying the API Platform Self-Ho helm uninstall gateway ``` -## What's Next? +## What's next? - [Adding and Managing Policies](manage-policies.md): Configure and enforce policies - [Analytics](analytics.md): Monitor API traffic and performance diff --git a/en/docs/cloud/api-platform-gateway/troubleshooting.md b/en/docs/cloud/api-platform-gateway/troubleshooting.md index 4a924f7c..7ce64526 100644 --- a/en/docs/cloud/api-platform-gateway/troubleshooting.md +++ b/en/docs/cloud/api-platform-gateway/troubleshooting.md @@ -2,9 +2,9 @@ This guide covers common issues you may encounter when deploying and operating the API Platform Self-Hosted Gateway, along with their solutions. -## Connection Issues +## Connection issues -### Gateway Not Connecting to Control Plane +### Gateway not connecting to control plane **Symptoms:** @@ -46,7 +46,7 @@ This guide covers common issues you may encounter when deploying and operating t noProxy: "localhost,127.0.0.1,.internal.example.com" ``` -### Intermittent Disconnections +### Intermittent disconnections **Symptoms:** @@ -77,9 +77,9 @@ This guide covers common issues you may encounter when deploying and operating t Ensure load balancers or firewalls don't have aggressive idle timeouts. -## Registration Issues +## Registration issues -### Invalid Gateway Token +### Invalid gateway token **Symptoms:** @@ -113,7 +113,7 @@ This guide covers common issues you may encounter when deploying and operating t cat /etc/bijira/env | grep BIJIRA_GATEWAY_TOKEN ``` -### Token Revoked +### Token revoked **Symptoms:** @@ -126,9 +126,9 @@ This guide covers common issues you may encounter when deploying and operating t 2. Update the gateway configuration. 3. Restart the gateway. -## Startup Issues +## Startup issues -### Gateway Pod/Container Not Starting +### Gateway pod/container not starting **Symptoms:** @@ -175,7 +175,7 @@ This guide covers common issues you may encounter when deploying and operating t bijira-gateway --config /etc/bijira/gateway.yaml --validate ``` -### Port Already in Use +### Port already in use **Symptoms:** @@ -199,9 +199,9 @@ This guide covers common issues you may encounter when deploying and operating t port: 8443 # Use alternative port ``` -## TLS/Certificate Issues +## TLS/Certificate issues -### Certificate Not Valid +### Certificate not valid **Symptoms:** @@ -232,7 +232,7 @@ This guide covers common issues you may encounter when deploying and operating t openssl rsa -noout -modulus -in private.key | openssl md5 ``` -### Certificate Expired +### Certificate expired **Symptoms:** @@ -256,9 +256,9 @@ This guide covers common issues you may encounter when deploying and operating t sudo systemctl reload bijira-gateway ``` -## Policy Issues +## Policy issues -### Policies Not Applied +### Policies not applied **Symptoms:** @@ -284,7 +284,7 @@ This guide covers common issues you may encounter when deploying and operating t grep -i "policy" /var/log/bijira/gateway.log ``` -### Policy Conflicts +### Policy conflicts **Symptoms:** @@ -301,9 +301,9 @@ This guide covers common issues you may encounter when deploying and operating t 3. Use the policy simulation tool in API Platform Console. -## Performance Issues +## Performance issues -### High Latency +### High latency **Symptoms:** @@ -345,7 +345,7 @@ This guide covers common issues you may encounter when deploying and operating t Ensure the gateway has low-latency access to backend services. -### High Memory Usage +### High memory usage **Symptoms:** @@ -379,9 +379,9 @@ This guide covers common issues you may encounter when deploying and operating t ttl: 300s ``` -## API Routing Issues +## API routing issues -### 404 Not Found Errors +### 404 not found errors **Symptoms:** @@ -402,7 +402,7 @@ This guide covers common issues you may encounter when deploying and operating t 3. **Verify the request path matches the API configuration.** -### 502 Bad Gateway Errors +### 502 bad gateway errors **Symptoms:** @@ -432,9 +432,9 @@ This guide covers common issues you may encounter when deploying and operating t readTimeout: 60s ``` -## Logging and Diagnostics +## Logging and diagnostics -### Enable Debug Logging +### Enable debug logging Temporarily enable debug logging for troubleshooting: @@ -446,7 +446,7 @@ logging: !!! warning Debug logging can generate large volumes of logs and impact performance. Disable after troubleshooting. -### Collect Diagnostic Information +### Collect diagnostic information When opening a support request, collect: @@ -479,7 +479,7 @@ When opening a support request, collect: df -h ``` -## Getting Help +## Getting help If you cannot resolve an issue using this guide: @@ -487,7 +487,7 @@ If you cannot resolve an issue using this guide: 2. **Search known issues:** Check the API Platform status page and release notes. 3. **Contact support:** Open a support ticket with diagnostic information. -## What's Next? +## What's next? - [Overview](overview.md): Self-Hosted Gateway overview - [Getting Started](getting-started.md): Quick start guide diff --git a/en/docs/cloud/api-platform-gateway/writing-a-custom-policy.md b/en/docs/cloud/api-platform-gateway/writing-a-custom-policy.md index 439705d0..2c5dd964 100644 --- a/en/docs/cloud/api-platform-gateway/writing-a-custom-policy.md +++ b/en/docs/cloud/api-platform-gateway/writing-a-custom-policy.md @@ -1,15 +1,15 @@ -# Writing a Custom Policy for the Self-Hosted Gateway +# Writing a custom policy for the Self-hosted gateway This guide shows how to build a custom policy using the gateway SDK. For full API details, see the [API Platform Gateway's Custom Policy SDK Documentation](https://pkg.go.dev/github.com/wso2/api-platform/sdk/core/policy/v1alpha2). -## What is a Policy? +## What is a policy? Policies allow you to enforce security, rate limiting, transformation, and other governance requirements on your APIs. -## How It Works +## How it works Every request and response that flows through the gateway passes through a **policy chain**. Each policy in the chain declares which phases it participates in, and the kernel calls the appropriate hook for each phase: @@ -41,9 +41,9 @@ Incoming Request A policy only participates in the phases it implements. For example, a policy that only inspects request headers does not implement the response interfaces. -## How to Write a Policy +## How to write a policy -### Step 1: Create the Policy +### Step 1: Create the policy Each policy lives in its own Go module. Create a "policies" directory inside your gateway: @@ -54,7 +54,7 @@ Each policy lives in its own Go module. Create a "policies" directory inside you └── policy-definition.yaml ``` -### Step 2: Implement the Base Policy Interface +### Step 2: Implement the base policy interface ```go package mypolicy @@ -82,7 +82,7 @@ func (p *MyPolicy) Mode() policy.ProcessingMode { } ``` -#### How to Choose Modes +#### How to choose modes | Setting | When to Use | |---------|-------------| @@ -92,11 +92,11 @@ func (p *MyPolicy) Mode() policy.ProcessingMode { !!! tip If you do not want your policy to process a specific phase, explicitly set it to `Skip`. -### Step 3: Implement Phase Interfaces +### Step 3: Implement phase interfaces Implement only the interfaces for phases you declared in `Mode()` in step 2. -#### Request Flow +#### Request flow **Request Header Phase** @@ -139,7 +139,7 @@ func (p *MyPolicy) OnRequestBody( !!! note Even if your policy is designed for streaming, you must still implement `OnRequestBody`. This acts as a fallback when the policy chain does not run in streaming mode. -#### Response Flow +#### Response flow **Response Header Phase** @@ -182,11 +182,11 @@ func (p *MyPolicy) OnResponseBody( !!! note Even if your policy is designed for streaming, you must still implement `OnResponseBody`. This acts as a fallback when the policy chain does not run in streaming mode. -### Step 4: Enable Streaming +### Step 4: Enable streaming Use streaming when processing SSE (Server-Sent Events) responses or large chunked transfers where you cannot or should not buffer the full body. Set `ResponseBodyMode: policy.BodyModeStream` (and/or `RequestBodyMode: policy.BodyModeStream`) in your `Mode()`, then implement the streaming interfaces. -#### Streaming Request +#### Streaming request Implement `StreamingRequestPolicy` to process request chunks: @@ -224,7 +224,7 @@ func (p *MyPolicy) OnRequestBody( } ``` -#### Streaming Response +#### Streaming response Implement `StreamingResponsePolicy` to process responses chunk by chunk: @@ -276,7 +276,7 @@ func (p *MyPolicy) OnResponseBody( } ``` -#### Gate-then-Stream Pattern +#### Gate-then-stream pattern A common pattern for guardrail policies is to accumulate chunks until you have enough data to make a decision, then switch to pass-through: @@ -288,7 +288,7 @@ func (p *MyPolicy) NeedsMoreResponseData(accumulated []byte) bool { } ``` -### Step 5: Factory Function +### Step 5: Factory function Initialize your policy and validate parameters: @@ -307,7 +307,7 @@ func GetPolicy( } ``` -### Step 6: Define Parameters +### Step 6: Define parameters Create a `policy-definition.yaml` in your policy directory: @@ -324,7 +324,7 @@ parameters: default: 1048576 ``` -### Step 7: Share Data Between Phases +### Step 7: Share data between phases Use the `Metadata` map to pass data between request and response phases: @@ -336,7 +336,7 @@ reqCtx.Metadata["clientID"] = clientID clientID := respCtx.Metadata["clientID"] ``` -### Step 8: Register and Build +### Step 8: Register and build Add your policy to gateway folder's `build.yaml` under `policies:` using `filePath` for local development: @@ -354,7 +354,7 @@ policies: gomodule: github.com/abc/policy-repo/policies/my-policy@v1 ``` -## What's Next? +## What's next? - [Building the Gateway with Custom Policies](build-gateway-with-custom-policies.md): Build a gateway image that includes your custom policy - [Apply Custom Policies to APIs](apply-custom-policies-to-apis.md): Sync your custom policy to the organization and apply it to APIs diff --git a/en/docs/cloud/bijira-concepts/data-planes.md b/en/docs/cloud/bijira-concepts/data-planes.md index 3100899f..246b6d8b 100644 --- a/en/docs/cloud/bijira-concepts/data-planes.md +++ b/en/docs/cloud/bijira-concepts/data-planes.md @@ -1,13 +1,13 @@ -# Data Planes +# Data planes API Platform’s architecture is built around two core components, i.e. the control plane and the data plane. -### Control Plane +### Control plane The control plane manages key administrative tasks, including the configuration of organizations, users, and projects. It also orchestrates the entire API Proxy development lifecycle, from creation and deployment to governance enforcement, observability enablement, and publishing to the Developer Portal for application developers to consume APIs. As a SaaS platform, the API Platform control plane oversees both cloud data planes and private data planes. It supports a wide range of user roles, including CIOs, architects, and developers. -### Data Plane +### Data plane The data plane is where user-deployed API Proxies run, based on configurations defined in the control plane. All traffic related to these API Proxies is confined within the data plane, ensuring that user data remains securely contained. API Platform supports two types of data planes. @@ -17,9 +17,9 @@ API Platform supports two types of data planes. ![Bijira high-level architecture with control plane, cloud data plane, and private data plane](../../assets/img/bijira-concepts/high-level-view.png) -## Private Data Planes +## Private data planes -### Infrastructure Compatibility +### Infrastructure compatibility API Platform private data planes can be deployed on most major cloud providers such as Azure, AWS, GCP, as well as on-premises environments. Minimum infrastructure requirements include: @@ -43,7 +43,7 @@ Setting up an API Platform PDP involves deploying components via Helm on the Kub All components are automatically updated, including security patches and bug fixes via the Flux Controller, which is connected to the Update Management System. -### Control Plane Connectivity +### Control plane connectivity Private data planes communicate with the control plane for ongoing operations. All communication is outbound only from the private data plane. If your organization’s network restricts outbound traffic, allow access to the control plane's public IP range. The following table details the required inbound and outbound connections for private data planes. @@ -65,7 +65,7 @@ The following table details the required inbound and outbound connections for pr All communications between the control plane and the private data plane are secured using TLS encryption. -### Observability Architecture +### Observability architecture The following diagram illustrates the log and observability architecture of an API Platform Azure PDP deployment. @@ -88,7 +88,7 @@ The API Platform private data plane is built with production-grade security in m End-to-end encryption is enforced using Cilium transparent encryption, ensuring secure and efficient network traffic flow. -### Private Data Plane Management Models +### Private data plane management models API Platform supports flexible management models for private data planes, facilitating collaboration between WSO2 and customers across diverse scenarios. diff --git a/en/docs/cloud/bijira-concepts/deployment-tracks.md b/en/docs/cloud/bijira-concepts/deployment-tracks.md index f8b7368f..cfcf6cf5 100644 --- a/en/docs/cloud/bijira-concepts/deployment-tracks.md +++ b/en/docs/cloud/bijira-concepts/deployment-tracks.md @@ -1,8 +1,8 @@ -# Deployment Tracks +# Deployment tracks Deployment Tracks in API Platform are structured pathways for simplified software component deployment. They act like advanced CI/CD pipelines, ensuring your components reach their destinations seamlessly, whether from source code or prebuilt images. They establish an organized and structured approach that minimizes the chances of errors and challenges that are typically associated with deployment workflows. -## The significance of Deployment Tracks +## The significance of deployment tracks Deployment Tracks offer practical solutions to enhance the API consumer experience by addressing two critical challenges: @@ -14,13 +14,13 @@ Deployment Tracks offer practical solutions to enhance the API consumer experien For streamlined deployments, API Platform dissects two integral approaches that leverage Deployment Tracks: the comprehensive CI/CD integration and the focused CD-Only strategy. -### CI/CD with Deployment Tracks +### CI/CD with deployment tracks A deployment track is linked to a particular branch within a GitHub repository. This connection is useful for handling deployments to various environments. On the API Platform's Deploy page, you can easily visualize the deployments to specific environments associated with your selected deployment track. Moreover, the deployment track has a functionality that initiates automatic deployments for the linked branch. When activated, merging a pull request (PR) triggers a deployment to the development environment. ![Source repository branches mapped to development and production environment deployment tracks](../../assets/img/bijira-concepts/deployment-tracks-source-repo.png){.cInlineImage-half} -### CD-Only strategy with Deployment Tracks +### CD-only strategy with deployment tracks If you're inclined to use your own Continuous Integration (CI) systems and want to harness the deployment track as a Continuous Deployment (CD) pipeline, you can seamlessly link deployment tracks to a container registry repository. This configuration empowers users to effortlessly deploy images sourced directly from the linked container registry repository. diff --git a/en/docs/cloud/bijira-concepts/organization.md b/en/docs/cloud/bijira-concepts/organization.md index 7b7e738b..ff24f14d 100644 --- a/en/docs/cloud/bijira-concepts/organization.md +++ b/en/docs/cloud/bijira-concepts/organization.md @@ -1,94 +1,94 @@ -# Organizations in API Platform - -Organizations are the foundational building blocks in API Platform, providing a secure and logical grouping of users, resources, and projects. This covers everything you need to know about organizations in API Platform, including their structure, management, permissions, and unique identifiers. - ---- - -## What is an Organization? - -An **organization** in API Platform is a logical container for users and their resources. Every user must belong to an organization to use API Platform. Organizations help isolate resources, manage access, and enable collaboration within a defined boundary. - -- **First-time user onboarding:** First-time users must create an organization and become its member upon signing up. -- **Resource isolation**: Users and resources in one organization cannot access those in another, unless explicitly invited. -- **Single organization per user**: A user can only create one organization, but may be invited to join others. - ---- - -## Switching between Organizations - -If you are a member of multiple organizations, you can easily switch between them by following steps below. - -1. In the API Platform Console header, click the **Organization** list. -2. Select the desired organization from the dropdown. - ---- - -## Inviting Members to Your Organization - -To collaborate, you can invite new members to your organization. (See the [Inviting Members](../administer/inviting-members.md) guide for step-by-step instructions.) - ---- - -## Managing User Permissions - -API Platform uses a combination of **groups** and **roles** to manage user permissions efficiently. - -### Groups - -A **group** is a collection of users with one or more roles assigned. Users inherit all permissions associated with the group's roles. For example, adding a user to the `API Publisher` group automatically grants them the `API Publisher` role. - -#### Predefined Groups - -API Platform provides several predefined groups, each mapped to specific roles. - -- **Admin**: Users who have full access to the API Platform (user management, application development, billing and subscription, etc.). -- **API Publisher**: Users who understand the technical aspects of the API (interfaces, documentation, versions, etc.) and create and publish APIs into the Developer Portal. -- **API Subscriber**: Users or Application Developers who search the Developer Portal to discover APIs and use them. They read the documentation and forums, rates/comments on the APIs, subscribes to APIs, obtain access tokens, and invokes the APIs. -- **Choreo Platform Engineer**: Users who perform tasks focusing on infrastructure, governance, service mesh, and monitoring. -- **Choreo DevOps**: Users who are involved in deployment management. - -> **Tip:** When creating a new group, always assign at least one role to ensure members have the required permissions. - -### Roles - -Roles define what actions a user can perform within an organization. The main roles in API Platform are: - -- **API Publisher**: Users who understand the technical aspects of the API (interfaces, documentation, versions, etc.) and create and publish APIs into the Developer Portal. -- **API Subscriber**: Users or Application Developers who search the Developer Portal to discover APIs and use them. They read the documentation and forums, rates/comments on the APIs, subscribes to APIs, obtain access tokens, and invokes the APIs. -- **Admin**: Users who have full access to the API Platform (user management, application development, billing and subscription, etc.) -- **Choreo DevOps**: Users who are involved in deployment management. -- **Choreo Platform Engineer**: Users who perform tasks focusing on infrastructure, governance, service mesh, and monitoring. - ---- - -## Organization Identifiers - -API Platform uses two unique identifiers for organizations, the **Organization ID** and the **Organization Handle**. - -### Organization ID - -A unique, system-generated identifier for each organization. To find your Organization ID: - -1. Go to the [API Platform Console](https://console.bijira.dev/) and sign in. -2. Click the **Organization** list in the header and select your organization. -3. In the left navigation, click **Settings**. -4. In the header, click the **Organization** list to open organization-level settings. -5. Under **Organization**, click **Copy ID**. - -### Organization Handle - -A unique, human-readable string that corresponds to your organization's name. To find your Organization Handle: - -1. Go to the [API Platform Console](https://console.bijira.dev/) and sign in. -2. Click the **Organization** list in the header and select your organization. -3. In the left navigation, click **Settings**. -4. Under **Organization**, click **Copy Handle**. - ---- - -## Best Practices for Organization Management - -- **Assign roles carefully**: Only grant users the permissions they need. -- **Use groups for easier management**: Assign roles to groups and add users to groups for scalable permission management. -- **Regularly review membership**: Periodically audit group memberships and roles to ensure security and compliance. -- **Leverage organization identifiers**: Use the Organization ID and Handle for integrations, support, and automation. +# Organizations in API Platform + +Organizations are the foundational building blocks in API Platform, providing a secure and logical grouping of users, resources, and projects. This covers everything you need to know about organizations in API Platform, including their structure, management, permissions, and unique identifiers. + +--- + +## What is an organization? + +An **organization** in API Platform is a logical container for users and their resources. Every user must belong to an organization to use API Platform. Organizations help isolate resources, manage access, and enable collaboration within a defined boundary. + +- **First-time user onboarding:** First-time users must create an organization and become its member upon signing up. +- **Resource isolation**: Users and resources in one organization cannot access those in another, unless explicitly invited. +- **Single organization per user**: A user can only create one organization, but may be invited to join others. + +--- + +## Switching between organizations + +If you are a member of multiple organizations, you can easily switch between them by following steps below. + +1. In the API Platform Console header, click the **Organization** list. +2. Select the desired organization from the dropdown. + +--- + +## Inviting members to your organization + +To collaborate, you can invite new members to your organization. (See the [Inviting Members](../administer/inviting-members.md) guide for step-by-step instructions.) + +--- + +## Managing user permissions + +API Platform uses a combination of **groups** and **roles** to manage user permissions efficiently. + +### Groups + +A **group** is a collection of users with one or more roles assigned. Users inherit all permissions associated with the group's roles. For example, adding a user to the `API Publisher` group automatically grants them the `API Publisher` role. + +#### Predefined groups + +API Platform provides several predefined groups, each mapped to specific roles. + +- **Admin**: Users who have full access to the API Platform (user management, application development, billing and subscription, etc.). +- **API Publisher**: Users who understand the technical aspects of the API (interfaces, documentation, versions, etc.) and create and publish APIs into the Developer Portal. +- **API Subscriber**: Users or Application Developers who search the Developer Portal to discover APIs and use them. They read the documentation and forums, rates/comments on the APIs, subscribes to APIs, obtain access tokens, and invokes the APIs. +- **Choreo Platform Engineer**: Users who perform tasks focusing on infrastructure, governance, service mesh, and monitoring. +- **Choreo DevOps**: Users who are involved in deployment management. + +> **Tip:** When creating a new group, always assign at least one role to ensure members have the required permissions. + +### Roles + +Roles define what actions a user can perform within an organization. The main roles in API Platform are: + +- **API Publisher**: Users who understand the technical aspects of the API (interfaces, documentation, versions, etc.) and create and publish APIs into the Developer Portal. +- **API Subscriber**: Users or Application Developers who search the Developer Portal to discover APIs and use them. They read the documentation and forums, rates/comments on the APIs, subscribes to APIs, obtain access tokens, and invokes the APIs. +- **Admin**: Users who have full access to the API Platform (user management, application development, billing and subscription, etc.) +- **Choreo DevOps**: Users who are involved in deployment management. +- **Choreo Platform Engineer**: Users who perform tasks focusing on infrastructure, governance, service mesh, and monitoring. + +--- + +## Organization identifiers + +API Platform uses two unique identifiers for organizations, the **Organization ID** and the **Organization Handle**. + +### Organization ID + +A unique, system-generated identifier for each organization. To find your Organization ID: + +1. Go to the [API Platform Console](https://console.bijira.dev/) and sign in. +2. Click the **Organization** list in the header and select your organization. +3. In the left navigation, click **Settings**. +4. In the header, click the **Organization** list to open organization-level settings. +5. Under **Organization**, click **Copy ID**. + +### Organization handle + +A unique, human-readable string that corresponds to your organization's name. To find your Organization Handle: + +1. Go to the [API Platform Console](https://console.bijira.dev/) and sign in. +2. Click the **Organization** list in the header and select your organization. +3. In the left navigation, click **Settings**. +4. Under **Organization**, click **Copy Handle**. + +--- + +## Best practices for organization management + +- **Assign roles carefully**: Only grant users the permissions they need. +- **Use groups for easier management**: Assign roles to groups and add users to groups for scalable permission management. +- **Regularly review membership**: Periodically audit group memberships and roles to ensure security and compliance. +- **Leverage organization identifiers**: Use the Organization ID and Handle for integrations, support, and automation. diff --git a/en/docs/cloud/bijira-concepts/project.md b/en/docs/cloud/bijira-concepts/project.md index af729ca7..0b91c46d 100644 --- a/en/docs/cloud/bijira-concepts/project.md +++ b/en/docs/cloud/bijira-concepts/project.md @@ -4,13 +4,13 @@ Projects are a core organizational unit in API Platform, designed to group relat --- -## What is a Project? +## What is a project? A **project** in API Platform is a logical grouping of API Proxies that typically work together to deliver a business capability. Projects help organize development, deployment, and management workflows for cloud-native applications. Each project is isolated from others, ensuring clear boundaries for resources, permissions, and deployments. --- -## Project Structure and Components +## Project structure and components A project may include: @@ -21,7 +21,7 @@ All components within a project can be managed together, versioned, and deployed --- -## Deployment Model +## Deployment model At deployment time, all components in a project are deployed into a single namespace within a Kubernetes cluster. This provides: diff --git a/en/docs/cloud/create-api-proxy/my-apis/graphql/import-api-contract.md b/en/docs/cloud/create-api-proxy/my-apis/graphql/import-api-contract.md index f43e3cca..6dbc9d8f 100644 --- a/en/docs/cloud/create-api-proxy/my-apis/graphql/import-api-contract.md +++ b/en/docs/cloud/create-api-proxy/my-apis/graphql/import-api-contract.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Import API Contract +# Import API contract A GraphQL API proxy operates based on the GraphQL query language specification. GraphQL provides a flexible and efficient approach to API development by allowing clients to request exactly the data they need, nothing more and nothing less. @@ -34,7 +34,7 @@ In this guide, you will: This creates the organization and opens the **Project Home** page of the default project created for you. -## Create an API Proxy +## Create an API proxy In this guide, you will use a sample URL to import a GraphQL schema definition and create a GraphQL API proxy. @@ -47,19 +47,19 @@ In this guide, you will use a sample URL to import a GraphQL schema definition a 6. Click **Next** and edit pre-defined values as needed. You can keep the default values for this sample. 7. Click **Create** to create the API Proxy. Wait for the setup to complete. -## Configure and Deploy the API Proxy +## Configure and deploy the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Select **Configure and Deploy** option from the **Deploy** dropdown and click it. 3. Select **External** as API Access Mode. 4. Click **Deploy**. -## Test the API Proxy +## Test the API proxy 1. Navigate to the **Test --> Console** page of the API Proxy. 2. Use the GraphQL Console to test the API Proxy. -## Promote the API Proxy to Production and Publish the API Proxy +## Promote the API proxy to production and publish the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Click **Promote**. This promotes the API proxy from the Development environment to the Production environment. @@ -67,7 +67,7 @@ In this guide, you will use a sample URL to import a GraphQL schema definition a 4. Click **Publish**. 5. In the **Publish API** dialog, click **Confirm** to proceed with publishing the API. If you want to change the display name, make the necessary changes and then click **Confirm**. This sets the API lifecycle state to **Published**. -## API Proxy Behavior +## API proxy behavior This GraphQL API Proxy enables clients to query data using GraphQL queries and mutations. Clients can request exactly the fields they need, reducing bandwidth and improving performance. The API supports complex queries that fetch related data in a single request, making it efficient for applications with varying data requirements. diff --git a/en/docs/cloud/create-api-proxy/my-apis/graphql/start-with-endpoint.md b/en/docs/cloud/create-api-proxy/my-apis/graphql/start-with-endpoint.md index 0a9db2cc..ed0f2d4a 100644 --- a/en/docs/cloud/create-api-proxy/my-apis/graphql/start-with-endpoint.md +++ b/en/docs/cloud/create-api-proxy/my-apis/graphql/start-with-endpoint.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Create API proxy from Start with Endpoint +# Create API proxy from start with endpoint A GraphQL API proxy operates based on the GraphQL query language specification. GraphQL provides a flexible and efficient approach to API development by allowing clients to request exactly the data they need, nothing more and nothing less. @@ -28,7 +28,7 @@ Unlike traditional REST APIs that require multiple endpoints for different resou This creates the organization and opens the **Project Home** page of the default project created for you. -## Create an API Proxy +## Create an API proxy In this guide, you will create a GraphQL API proxy using an endpoint. @@ -45,19 +45,19 @@ In this guide, you will create a GraphQL API proxy using an endpoint. 9. Click **Create** to create the API Proxy. Wait for the setup to complete. -## Configure and Deploy the API Proxy +## Configure and deploy the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Select **Configure and Deploy** option from the **Deploy** dropdown and click it. 3. Select **External** as API Access Mode. 4. Click **Deploy**. -## Test the API Proxy +## Test the API proxy 1. Navigate to the **Test --> Console** page of the API Proxy. 2. Use the GraphQL Console to test the API Proxy. -## Promote the API Proxy to Production and Publish the API Proxy +## Promote the API proxy to production and publish the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Click **Promote**. This promotes the API proxy from the Development environment to the Production environment. diff --git a/en/docs/cloud/create-api-proxy/my-apis/http/create-with-genai.md b/en/docs/cloud/create-api-proxy/my-apis/http/create-with-genai.md index fecccd7f..36a72428 100644 --- a/en/docs/cloud/create-api-proxy/my-apis/http/create-with-genai.md +++ b/en/docs/cloud/create-api-proxy/my-apis/http/create-with-genai.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Create API with Generative AI +# Create API with generative AI An API proxy acts as an intermediary between an existing API and API Platform, intercepting all requests made to the API.It also functions as a managed API, allowing you to apply essential API management features such as security policies and rate limiting. @@ -26,7 +26,7 @@ An API proxy acts as an intermediary between an existing API and API Platform, i This creates the organization and opens the **Project Home** page of the default project created for you. -## Create an API Proxy +## Create an API proxy In this guide, you will create an API proxy with AI. @@ -38,19 +38,19 @@ In this guide, you will create an API proxy with AI. 6. Add the Description as `Sample proxy for E-Learning Platform` 7. Click **Create** to create the API Proxy. Wait for the setup to complete. -## Configure and Deploy the API Proxy +## Configure and deploy the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Select **Configure and Deploy** option from the **Deploy** dropdown and click **Configure and Deploy** button. 3. Select **External** as API Access Mode. 4. Click **Deploy**. -## Test the API Proxy +## Test the API proxy 1. Navigate to the **Test --> Console** page of the API Proxy. 2. Use the OpenAPI Console to test the API Proxy. -## Promote the API Proxy to Production and Publish the API Proxy +## Promote the API proxy to production and publish the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Click **Promote**. This promotes the API proxy from the Development environment to the Production environment. diff --git a/en/docs/cloud/create-api-proxy/my-apis/http/import-api-contract.md b/en/docs/cloud/create-api-proxy/my-apis/http/import-api-contract.md index a984d32b..b9a77593 100644 --- a/en/docs/cloud/create-api-proxy/my-apis/http/import-api-contract.md +++ b/en/docs/cloud/create-api-proxy/my-apis/http/import-api-contract.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Import API Contract +# Import API contract An API proxy acts as an intermediary between an existing API and API Platform, intercepting all requests made to the API.It also functions as a managed API, allowing you to apply essential API management features such as security policies and rate limiting. @@ -32,7 +32,7 @@ In this guide, you will: This creates the organization and opens the **Project Home** page of the default project created for you. -## Create an API Proxy +## Create an API proxy In this guide, you will specify a URL to an OpenAPI definition of a sample API to create an API proxy. @@ -48,19 +48,19 @@ In this guide, you will specify a URL to an OpenAPI definition of a sample API t 5. Click **Next** and edit pre-defined values as needed. You can keep the default values for this sample. 6. Click **Create** to create the API Proxy. Wait for the setup to complete. -## Configure and Deploy the API Proxy +## Configure and deploy the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Select **Configure and Deploy** option from the **Deploy** dropdown and click it. 3. Select **External** as API Access Mode. 4. Click **Deploy**. -## Test the API Proxy +## Test the API proxy 1. Navigate to the **Test --> OpenAPI Console** page of the API Proxy. 2. Use the OpenAPI Console to test the API Proxy. -## Promote the API Proxy to Production and Publish the API Proxy +## Promote the API proxy to production and publish the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Click **Promote**. This promotes the API proxy from the Development environment to the Production environment. @@ -68,7 +68,7 @@ In this guide, you will specify a URL to an OpenAPI definition of a sample API t 4. Click **Publish**. 5. In the **Publish API** dialog, click **Confirm** to proceed with publishing the API. If you want to change the display name, make the necessary changes and then click **Confirm**. This sets the API lifecycle state to **Published**. -## API Proxy Behavior +## API proxy behavior The Reading List API Proxy provides the following functionality: diff --git a/en/docs/cloud/create-api-proxy/my-apis/http/import-api-from-github.md b/en/docs/cloud/create-api-proxy/my-apis/http/import-api-from-github.md index 0f529c2e..f5c02a95 100644 --- a/en/docs/cloud/create-api-proxy/my-apis/http/import-api-from-github.md +++ b/en/docs/cloud/create-api-proxy/my-apis/http/import-api-from-github.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Create an API Proxy from a GitHub Repository Source +# Create an API proxy from a GitHub repository source An API proxy acts as an intermediary between an existing API and API Platform, intercepting all requests made to the API. It also functions as a managed API, allowing you to apply essential API management features such as security policies and rate limiting. @@ -32,7 +32,7 @@ An API proxy acts as an intermediary between an existing API and API Platform, i When creating an API proxy from a GitHub repository, you must include a `component.yaml` configuration file in your repository. This file must be located at `.choreo/component.yaml` within your API directory. -### Required Configuration +### Required configuration The `component.yaml` file for API proxies must include the following structure: @@ -42,7 +42,7 @@ proxy: schemaFilePath: openapi.yaml ``` -### Configuration Fields +### Configuration fields | **Field** | **Required** | **Description** | |-----------|--------------|-----------------| @@ -100,7 +100,7 @@ You can create an API proxy either by selecting the source from a GitHub reposit !!! note The API contract cannot be modified after proxy creation. Therefore, any changes to the API contract in the GitHub repository will not apply to the created proxy. -## Step 2: Build and Deploy the API proxy +## Step 2: Build and deploy the API proxy !!! info A build starts automatically when you create the API proxy, and you will be redirected to the **Overview** page. diff --git a/en/docs/cloud/create-api-proxy/my-apis/http/start-from-scratch.md b/en/docs/cloud/create-api-proxy/my-apis/http/start-from-scratch.md index 1b3c17ba..5e6f77d3 100644 --- a/en/docs/cloud/create-api-proxy/my-apis/http/start-from-scratch.md +++ b/en/docs/cloud/create-api-proxy/my-apis/http/start-from-scratch.md @@ -11,7 +11,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Create API Proxy from Scratch +# Create API proxy from scratch An API proxy acts as an intermediary between an existing API and API Platform, intercepting all requests made to the API.It also functions as a managed API, allowing you to apply essential API management features such as security policies and rate limiting. @@ -25,7 +25,7 @@ An API proxy acts as an intermediary between an existing API and API Platform, i This creates the organization and opens the **Project Home** page of the default project created for you. -## Create an API Proxy +## Create an API proxy In this guide, you will create an API proxy from the Scratch. @@ -46,19 +46,19 @@ In this guide, you will create an API proxy from the Scratch. 5. Click **Create** to create the API Proxy. Wait for the setup to complete. -## Configure and Deploy the API Proxy +## Configure and deploy the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Select **Configure and Deploy** option from the **Deploy** dropdown and click **Configure and Deploy** button. 3. Select **External** as API Access Mode. 4. Click **Deploy**. -## Test the API Proxy +## Test the API proxy 1. Navigate to the **Test --> Console** page of the API Proxy. 2. Use the OpenAPI Console to test the API Proxy. -## Promote the API Proxy to Production and Publish the API Proxy +## Promote the API proxy to production and publish the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Click **Promote**. This promotes the API proxy from the Development environment to the Production environment. diff --git a/en/docs/cloud/create-api-proxy/my-apis/http/start-with-endpoint.md b/en/docs/cloud/create-api-proxy/my-apis/http/start-with-endpoint.md index ca158d83..86d885a9 100644 --- a/en/docs/cloud/create-api-proxy/my-apis/http/start-with-endpoint.md +++ b/en/docs/cloud/create-api-proxy/my-apis/http/start-with-endpoint.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Create API proxy from Start with Endpoint +# Create API proxy from start with endpoint An API proxy acts as an intermediary between an existing API and API Platform, intercepting all requests made to the API.It also functions as a managed API, allowing you to apply essential API management features such as security policies and rate limiting. @@ -26,7 +26,7 @@ An API proxy acts as an intermediary between an existing API and API Platform, i This creates the organization and opens the **Project Home** page of the default project created for you. -## Create an API Proxy +## Create an API proxy In this guide, you will create an API proxy using an endpoint. @@ -53,19 +53,19 @@ In this guide, you will create an API proxy using an endpoint. 7. Click **Create** to create the API Proxy. Wait for the setup to complete. -## Configure and Deploy the API Proxy +## Configure and deploy the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Select **Configure and Deploy** option from the **Deploy** dropdown and click **Configure and Deploy** button. 3. Select **External** as API Access Mode. 4. Click **Deploy**. -## Test the API Proxy +## Test the API proxy 1. Navigate to the **Test --> Console** page of the API Proxy. 2. Use the OpenAPI Console to test the API Proxy. -## Promote the API Proxy to Production and Publish the API Proxy +## Promote the API proxy to production and publish the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Click **Promote**. This promotes the API proxy from the Development environment to the Production environment. diff --git a/en/docs/cloud/create-api-proxy/my-apis/websocket/create-with-genai.md b/en/docs/cloud/create-api-proxy/my-apis/websocket/create-with-genai.md index cde9e059..8a470501 100644 --- a/en/docs/cloud/create-api-proxy/my-apis/websocket/create-with-genai.md +++ b/en/docs/cloud/create-api-proxy/my-apis/websocket/create-with-genai.md @@ -13,7 +13,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Create a WebSocket API with Generative AI +# Create a WebSocket API with generative AI A WebSocket API proxy operates based on the WebSocket protocol specification (RFC 6455). This protocol is designed to overcome the limitations of the traditional HTTP request-response model by establishing a single, persistent TCP connection between the client and the server. @@ -29,7 +29,7 @@ The WebSocket connection begins with an initial handshake that leverages the HTT This creates the organization and opens the **Project Home** page of the default project created for you. -## Create an API Proxy +## Create an API proxy In this guide, you will create an API proxy with AI. @@ -41,19 +41,19 @@ In this guide, you will create an API proxy with AI. 6. Add the Description as `Sample proxy for Chat Application` 7. Click **Create** to create the API Proxy. Wait for the setup to complete. -## Configure and Deploy the API Proxy +## Configure and deploy the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Select **Configure and Deploy** option from the **Deploy** dropdown and click **Configure and Deploy** button. 3. Select **External** as API Access Mode. 4. Click **Deploy**. -## Test the API Proxy +## Test the API proxy 1. Navigate to the **Test --> Console** page of the API Proxy. 2. Use the OpenAPI Console to test the API Proxy. -## Promote the API Proxy to Production and Publish the API Proxy +## Promote the API proxy to production and publish the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Click **Promote**. This promotes the API proxy from the Development environment to the Production environment. diff --git a/en/docs/cloud/create-api-proxy/my-apis/websocket/import-api-contract.md b/en/docs/cloud/create-api-proxy/my-apis/websocket/import-api-contract.md index 6bfc9121..909f7980 100644 --- a/en/docs/cloud/create-api-proxy/my-apis/websocket/import-api-contract.md +++ b/en/docs/cloud/create-api-proxy/my-apis/websocket/import-api-contract.md @@ -13,7 +13,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Import API Contract +# Import API contract A WebSocket API proxy operates based on the WebSocket protocol specification (RFC 6455). This protocol is designed to overcome the limitations of the traditional HTTP request-response model by establishing a single, persistent TCP connection between the client and the server. @@ -35,7 +35,7 @@ In this guide, you will: This creates the organization and opens the **Project Home** page of the default project created for you. -## Create an API Proxy +## Create an API proxy In this guide, you will specify a URL to an AsyncAPI definition of a sample API to create a WebSocket API proxy. @@ -52,19 +52,19 @@ In this guide, you will specify a URL to an AsyncAPI definition of a sample API 5. Click **Next** and edit pre-defined values as needed. You can keep the default values for this sample. 6. Click **Create** to create the API Proxy. Wait for the setup to complete. -## Configure and Deploy the API Proxy +## Configure and deploy the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Select **Configure and Deploy** option from the **Deploy** dropdown and click it. 3. Select **External** as API Access Mode. 4. Click **Deploy**. -## Test the API Proxy +## Test the API proxy 1. Navigate to the **Test --> Console** page of the API Proxy. 2. Use the Console to test the API Proxy. -## Promote the API Proxy to Production and Publish the API Proxy +## Promote the API proxy to production and publish the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Click **Promote**. This promotes the API proxy from the Development environment to the Production environment. @@ -72,6 +72,6 @@ In this guide, you will specify a URL to an AsyncAPI definition of a sample API 4. Click **Publish**. 5. In the **Publish API** dialog, click **Confirm** to proceed with publishing the API. If you want to change the display name, make the necessary changes and then click **Confirm**. This sets the API lifecycle state to **Published**. -## API Proxy Behavior +## API proxy behavior This Chat Service API Proxy enables clients to establish persistent connections with the server, allowing multiple users to connect simultaneously and exchange real-time messages. It also supports broadcasting messages to all users participating in the chat. diff --git a/en/docs/cloud/create-api-proxy/my-apis/websocket/quotas-and-limitations.md b/en/docs/cloud/create-api-proxy/my-apis/websocket/quotas-and-limitations.md index 1158db1a..591dba6f 100644 --- a/en/docs/cloud/create-api-proxy/my-apis/websocket/quotas-and-limitations.md +++ b/en/docs/cloud/create-api-proxy/my-apis/websocket/quotas-and-limitations.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "reference" --- -## Limitations for WebSocket API Proxies +## Limitations for WebSocket API proxies Explore key limitations in API Platform WebSocket API proxies, covering areas like maximum number of connections, maximum connection duration, and more. You can gain insights into the limitations to enhance your understanding and optimize your use of WebSocket API proxies effectively. diff --git a/en/docs/cloud/create-api-proxy/my-apis/websocket/start-from-scratch.md b/en/docs/cloud/create-api-proxy/my-apis/websocket/start-from-scratch.md index 4270f87a..91ebfead 100644 --- a/en/docs/cloud/create-api-proxy/my-apis/websocket/start-from-scratch.md +++ b/en/docs/cloud/create-api-proxy/my-apis/websocket/start-from-scratch.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Create API Proxy from Scratch +# Create API proxy from scratch A WebSocket API proxy operates based on the WebSocket protocol specification (RFC 6455). This protocol is designed to overcome the limitations of the traditional HTTP request-response model by establishing a single, persistent TCP connection between the client and the server. @@ -28,7 +28,7 @@ The WebSocket connection begins with an initial handshake that leverages the HTT This creates the organization and opens the **Project Home** page of the default project created for you. -## Create an API Proxy +## Create an API proxy In this guide, you will create a WebSocket API proxy from the Scratch. @@ -50,19 +50,19 @@ The WebSocket connection begins with an initial handshake that leverages the HTT 5. Click **Create** to create the API Proxy. Wait for the setup to complete. -## Configure and Deploy the API Proxy +## Configure and deploy the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Select **Configure and Deploy** option from the **Deploy** dropdown and click **Configure and Deploy** button. 3. Select **External** as API Access Mode. 4. Click **Deploy**. -## Test the API Proxy +## Test the API proxy 1. Navigate to the **Test --> Console** page of the API Proxy. 2. Use the OpenAPI Console to test the API Proxy. -## Promote the API Proxy to Production and Publish the API Proxy +## Promote the API proxy to production and publish the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Click **Promote**. This promotes the API proxy from the Development environment to the Production environment. diff --git a/en/docs/cloud/create-api-proxy/my-apis/websocket/start-with-endpoint.md b/en/docs/cloud/create-api-proxy/my-apis/websocket/start-with-endpoint.md index 4ae11120..34f8eb0b 100644 --- a/en/docs/cloud/create-api-proxy/my-apis/websocket/start-with-endpoint.md +++ b/en/docs/cloud/create-api-proxy/my-apis/websocket/start-with-endpoint.md @@ -13,7 +13,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Create API proxy from Start with Endpoint +# Create API proxy from start with endpoint A WebSocket API proxy operates based on the WebSocket protocol specification (RFC 6455). This protocol is designed to overcome the limitations of the traditional HTTP request-response model by establishing a single, persistent TCP connection between the client and the server. @@ -30,7 +30,7 @@ The WebSocket connection begins with an initial handshake that leverages the HTT This creates the organization and opens the **Project Home** page of the default project created for you. -## Create an API Proxy +## Create an API proxy In this guide, you will create a WebSocket API proxy using an endpoint. @@ -58,19 +58,19 @@ In this guide, you will create a WebSocket API proxy using an endpoint. 7. Click **Create** to create the API Proxy. Wait for the setup to complete. -## Configure and Deploy the API Proxy +## Configure and deploy the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Select **Configure and Deploy** option from the **Deploy** dropdown and click **Configure and Deploy** button. 3. Select **External** as API Access Mode. 4. Click **Deploy**. -## Test the API Proxy +## Test the API proxy 1. Navigate to the **Test --> Console** page of the API Proxy. 2. Use the OpenAPI Console to test the API Proxy. -## Promote the API Proxy to Production and Publish the API Proxy +## Promote the API proxy to production and publish the API proxy 1. Navigate to the **Deploy** page of the API Proxy. 2. Click **Promote**. This promotes the API proxy from the Development environment to the Production environment. diff --git a/en/docs/cloud/create-api-proxy/overview.md b/en/docs/cloud/create-api-proxy/overview.md index 36647948..3feb88b5 100644 --- a/en/docs/cloud/create-api-proxy/overview.md +++ b/en/docs/cloud/create-api-proxy/overview.md @@ -29,7 +29,7 @@ Creating an **API proxy** for: - [Start from Scratch](my-apis/http/start-from-scratch.md) - [Create with GenAI](my-apis/http/create-with-genai.md) -- **Third Party APIs(Egress APIs)** +- **Third party APIs (Egress APIs)** An API Proxy can be created to front an Endpoint or API which is managed by a third party in following scenarios: diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/awsbedrock.md b/en/docs/cloud/create-api-proxy/third-party-apis/awsbedrock.md index 764558fc..dd3aa6fc 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/awsbedrock.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/awsbedrock.md @@ -13,13 +13,13 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Create an API Proxy for an AWS Bedrock AI API +# Create an API proxy for an AWS Bedrock AI API Follow the steps below to create an AI API: --- -## 1. Access the API Platform Console +## 1. Access the API Platform console 1. Sign in to the [API Platform Console](https://console.bijira.dev/) and select your project. @@ -49,7 +49,7 @@ Follow the steps below to create an AI API: --- -## 3. Configure Backend Settings +## 3. Configure backend settings 1. In the left navigation menu, click **Develop**, then select **Policy**. @@ -68,7 +68,7 @@ Follow the steps below to create an AI API: ![Endpoint Configuration dialog showing AWS Configurations with Region, Access Key, and Secret Key fields](../../../assets/img/create-api-proxy/third-party-apis/ai-apis/aws-key.png) -## 4. Deploy to development and Production Environments +## 4. Deploy to development and production environments 1. In the left navigation menu, click **Deploy**, Deploy to Development environment @@ -82,7 +82,7 @@ Follow the steps below to create an AI API: --- -## Next Steps +## Next steps - **Test the AI API** to ensure it correctly forwards requests to the AI service. See [Test REST Endpoints via the OpenAPI Console](../../test-api-proxy/openapi-console.md). diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/azure-ai.md b/en/docs/cloud/create-api-proxy/third-party-apis/azure-ai.md index bfa7660d..c6cb58c5 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/azure-ai.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/azure-ai.md @@ -13,13 +13,13 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Create an API Proxy for an Azure Open AI API +# Create an API proxy for an Azure Open AI API Follow the steps below to create an AI API: --- -## 1. Access the API Platform Console +## 1. Access the API Platform console 1. Sign in to the [API Platform Console](https://console.bijira.dev/) and select your project. @@ -49,7 +49,7 @@ Follow the steps below to create an AI API: --- -## 3. Configure Backend Settings +## 3. Configure backend settings 1. In the left navigation menu, click **Develop**, then select **Policy**. @@ -68,7 +68,7 @@ Follow the steps below to create an AI API: ![Endpoint Configuration dialog showing Azure OpenAI endpoint URL with api-key header and API key input fields](../../../assets/img/create-api-proxy/third-party-apis/ai-apis/azure-endpoint-value.png) -## 4. Deploy to development and Production Environments +## 4. Deploy to development and production environments 1. In the left navigation menu, click **Deploy**, Deploy to Development environment @@ -82,7 +82,7 @@ Follow the steps below to create an AI API: --- -## Next Steps +## Next steps - **Test the AI API** to ensure it correctly forwards requests to the AI service. See [Test REST Endpoints via the OpenAPI Console](../../test-api-proxy/openapi-console.md). diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/claude.md b/en/docs/cloud/create-api-proxy/third-party-apis/claude.md index 5bdc83e0..5d3b2782 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/claude.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/claude.md @@ -13,13 +13,13 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Create an API Proxy for an Anthropic Claude AI API +# Create an API proxy for an Anthropic Claude AI API Follow the steps below to create an AI API: --- -## 1. Access the API Platform Console +## 1. Access the API Platform console 1. Sign in to the [API Platform Console](https://console.bijira.dev/) and select your project. @@ -49,7 +49,7 @@ Follow the steps below to create an AI API: --- -## 3. Configure Backend Settings +## 3. Configure backend settings 1. In the left navigation menu, click **Develop**, then select **Policy**. @@ -68,7 +68,7 @@ Follow the steps below to create an AI API: ![Endpoint Configuration dialog showing Anthropic Claude endpoint URL with x-api-key header and API key input fields](../../../assets/img/create-api-proxy/third-party-apis/ai-apis/claude-key.png) -## 4. Deploy to development and Production Environments +## 4. Deploy to development and production environments 1. In the left navigation menu, click **Deploy**, Deploy to Development environment @@ -82,7 +82,7 @@ Follow the steps below to create an AI API: --- -## Next Steps +## Next steps - **Test the AI API** to ensure it correctly forwards requests to the AI service. See [Test REST Endpoints via the OpenAPI Console](../../test-api-proxy/openapi-console.md). diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/get-from-marketplace.md b/en/docs/cloud/create-api-proxy/third-party-apis/get-from-marketplace.md index 8b655cd3..7addaa96 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/get-from-marketplace.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/get-from-marketplace.md @@ -12,26 +12,26 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Creating an API Proxy from Marketplace +# Creating an API proxy from marketplace API Platform provides built-in support for multiple well-known third-party APIs through the API Platform Marketplace. The marketplace contains API contracts for these third-party services, allowing you to create and publish API proxies effortlessly. -## Steps to Create an API Proxy from the Marketplace +## Steps to create an API proxy from the marketplace Follow these steps to create an API proxy for a third-party API available in the API Platform Marketplace: -### 1. Access the API Platform Console +### 1. Access the API Platform console 1. Sign in to the [API Platform Console](https://console.bijira.dev/) and select your project. -### 2. Select a Third-Party API +### 2. Select a third-party API 1. Click **+Create**. 2. Navigate to **Create an API Proxy for Third-Party APIs (Egress)** and click **Get From Marketplace**. 3. In the **Create API Proxy from Marketplace** page, browse or search for the desired third-party API. 4. Select the API you want to integrate. -### 3. Configure API Proxy Details +### 3. Configure API proxy details 1. Update the required API proxy details, such as: - API Name @@ -46,12 +46,12 @@ Follow these steps to create an API proxy for a third-party API available in the Once created, the overview page of the new API proxy appears. -### 4. Configure Backend Settings +### 4. Configure backend settings 1. In the left navigation menu, click **Develop**, then select **Policy**. 2. Depending on the third-party API requirements, configure **Endpoint Configurations** or set up an **API-level mediation policy** to handle authentication and authorization. -#### Example: Configuring the `Currency API` +#### Example: Configuring the `currency API` To integrate the `Currency API`, follow these steps: @@ -65,7 +65,7 @@ To integrate the `Currency API`, follow these steps: ![Policy page with Configurations panel showing Currency API endpoint URL, API Key Header, and API Key input fields](../../../assets/img/create-api-proxy/third-party-apis/marketplace/third-party-api-backend-configuration.png) -### Next Steps +### Next steps - Test the API proxy to ensure it correctly forwards requests to the third-party API. See [Test REST Endpoints via the OpenAPI Console](../../test-api-proxy/openapi-console.md). - Apply additional policies if needed (e.g., rate limiting, security policies). See [Policy Overview](../../develop-api-proxy/policy/attach-and-manage-policies.md#attach-a-policy). diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails.md b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails.md index 9f3346a4..7473d465 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails.md @@ -13,7 +13,7 @@ last_updated: 2026-06-18 content_type: "overview" --- -# AI Guardrails +# AI guardrails Guardrails are a set of guidelines and best practices designed to ensure the safe and effective use of AI systems. They help mitigate risks and promote responsible AI usage. API Platform provides 3 types of guardrails to enhance the security and reliability of AI APIs: @@ -24,8 +24,8 @@ Guardrails are a set of guidelines and best practices designed to ensure the saf - [Content Length Guardrail](guardrails/basic-guardrails/content-length-guardrail.md) - [URL Guardrail](guardrails/basic-guardrails/url-guardrail.md) - [Regex PII Masking](guardrails/basic-guardrails/regex-pii-masking.md) -- **Advanced Guardrails**: For more sophisticated AI applications that require enhanced flexibility and control, API Platform integrates with Guardrails AI—an extensible framework that enables seamless integration of complex AI models and services. This framework allows you to leverage open-source fine-tuned language models to implement advanced guardrails tailored to your specific requirements. +- **Advanced guardrails**: For more sophisticated AI applications that require enhanced flexibility and control, API Platform integrates with Guardrails AI—an extensible framework that enables seamless integration of complex AI models and services. This framework allows you to leverage open-source fine-tuned language models to implement advanced guardrails tailored to your specific requirements. - [PII Masking](guardrails/advanced-guardrails/pii-masking.md) -- **Third Party Guardrail Integrations**: These are integrations with third-party services that offer additional security and compliance features for AI APIs. +- **Third-party guardrail integrations**: These are integrations with third-party services that offer additional security and compliance features for AI APIs. - [Azure Content Safety Content Moderation](guardrails/third-party-guardrail-integrations/azure-content-safety-content-moderation.md) - [AWS Bedrock Guardrails](guardrails/third-party-guardrail-integrations/aws-bedrock-guardrail.md) diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/advanced-guardrails/pii-masking.md b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/advanced-guardrails/pii-masking.md index 1ef689c0..a14ff9c9 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/advanced-guardrails/pii-masking.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/advanced-guardrails/pii-masking.md @@ -13,11 +13,11 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# PII Masking (using Guardrails AI) +# PII masking (using guardrails AI) The PII Masking policy allows you to mask Personally Identifiable Information (PII) in the request and response payloads using an fine-tuned Guardrails AI model. This policy is particularly useful for ensuring that sensitive information is not exposed in AI-generated content, thereby enhancing security and compliance with data protection regulations. -## Configure PII Masking +## Configure PII masking 1. In the left navigation menu, click **Develop**, then select **Policy**. @@ -40,14 +40,14 @@ The PII Masking policy allows you to mask Personally Identifiable Information (P !!! note "PII Unmasking with PII Masking" If you want to use the PII Masking for PII unmasking, you must attach the policy to both the request and response flows. This allows the policy to mask PII in the request and unmask it in the response. Moreover, the `Redact PII` option should be disabled in both flows to allow the PII to be restored in the response. If you enable `Redact PII` in the response flow, the PII will be permanently redacted and not restored. -### Sample PII Masking Configuration +### Sample PII masking configuration - Guardrail Name: `PII Masking` - PII Entities: `EMAIL,URL` - JSON Path: `$.messages[0].content` - Redact PII: `true` -### Sample Payload to be intervened from the PII Masking +### Sample payload to be intervened from the PII masking ```json { @@ -60,7 +60,7 @@ The PII Masking policy allows you to mask Personally Identifiable Information (P } ``` -### Sample Payload after intervention from PII Masking +### Sample payload after intervention from PII masking ```json { diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/content-length-guardrail.md b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/content-length-guardrail.md index a20c70ae..b6a1bae1 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/content-length-guardrail.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/content-length-guardrail.md @@ -12,11 +12,11 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Content Length Guardrail +# Content length guardrail This policy provides the capability to perform content-byte-length validation on incoming or outgoing JSON payloads. This component acts as a guardrail to enforce specific content moderation rules based on configurable minimum and maximum byte sizes and JSONPath expressions. -## Configure Content Length Guardrail +## Configure content length guardrail 1. In the left navigation menu, click **Develop**, then select **Policy**. @@ -37,7 +37,7 @@ This policy provides the capability to perform content-byte-length validation on 4. Save the API and Deploy the API to apply the policy to the gateway. -### Sample Content Length Guardrail Configuration +### Sample content length guardrail configuration - Guardrail Name: `Content Length Guardrail` - Minimum Content Length: `10` @@ -46,7 +46,7 @@ This policy provides the capability to perform content-byte-length validation on - Invert the Guardrail Decision: `false` - Show Guardrail Assessment: `true` -### Sample Payload to be intervened from the Content Length Guardrail +### Sample payload to be intervened from the content length guardrail ```json { @@ -59,7 +59,7 @@ This policy provides the capability to perform content-byte-length validation on } ``` -### Sample Response after Content Length Guardrail Intervention +### Sample response after content length guardrail intervention ```json { diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/regex-guardrail.md b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/regex-guardrail.md index b319f5bb..fd8500a2 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/regex-guardrail.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/regex-guardrail.md @@ -12,11 +12,11 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Regex Guardrail +# Regex guardrail This policy provides the capability to perform regular expression-based validation on incoming or outgoing JSON payloads. This component acts as a guardrail to enforce specific security or compliance rules based on configurable regex patterns and JSON path expressions. -## Configure Regex Guardrail +## Configure regex guardrail 1. In the left navigation menu, click **Develop**, then select **Policy**. @@ -36,7 +36,7 @@ This policy provides the capability to perform regular expression-based validati 4. Save the API and Deploy the API to apply the policy to the gateway. -### Sample Regex Guardrail Configuration +### Sample regex guardrail configuration - Guardrail Name: `Regex Guardrail` - Regex Pattern: `(?i)ignore\s+all\s+.*instructions\s+and\s+do\s+.*now` @@ -44,7 +44,7 @@ This policy provides the capability to perform regular expression-based validati - Invert the Guardrail Decision: `true` - Show Guardrail Assessment: `true` -### Sample Payload to be intervened from the Regex Guardrail +### Sample payload to be intervened from the regex guardrail ```json { @@ -57,7 +57,7 @@ This policy provides the capability to perform regular expression-based validati } ``` -### Sample Response after Regex Guardrail Intervention +### Sample response after regex guardrail intervention ```json { diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/regex-pii-masking.md b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/regex-pii-masking.md index 1bd2ab19..ed76e612 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/regex-pii-masking.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/regex-pii-masking.md @@ -13,11 +13,11 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Regex PII Masking +# Regex PII masking This policy provides the capability to perform regular expression-based validation on incoming or outgoing JSON payloads specifically for Personally Identifiable Information (PII) masking. This component acts as a guardrail to enforce specific security or compliance rules based on configurable regex patterns and JSON path expressions. -## Configure Regex PII Masking +## Configure regex PII masking 1. In the left navigation menu, click **Develop**, then select **Policy**. @@ -40,7 +40,7 @@ This policy provides the capability to perform regular expression-based validati !!! note "PII Unmasking with Regex PII Masking" If you want to use the Regex PII Masking for PII unmasking, you must attach the policy to both the request and response flows. This allows the policy to mask PII in the request and unmask it in the response. Moreover, the `Redact PII` option should be disabled in both flows to allow the PII to be restored in the response. If you enable `Redact PII` in the response flow, the PII will be permanently redacted and not restored. -### Sample Regex PII Masking Configuration +### Sample regex PII masking configuration - Guardrail Name: `Regex Guardrail` - PII Entities: @@ -55,7 +55,7 @@ This policy provides the capability to perform regular expression-based validati - JSON Path: `$.messages[0].content` - Redact PII: `true` -### Sample Payload to be intervened from the Regex PII Masking +### Sample payload to be intervened from the regex PII masking ```json { @@ -68,7 +68,7 @@ This policy provides the capability to perform regular expression-based validati } ``` -### Sample Payload after intervention from Regex PII Masking +### Sample payload after intervention from regex PII masking ```json { diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/sentence-count-guardrail.md b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/sentence-count-guardrail.md index d5dfecb0..a3776568 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/sentence-count-guardrail.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/sentence-count-guardrail.md @@ -12,11 +12,11 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Sentence Count Guardrail +# Sentence count guardrail This policy provides the capability to perform sentence count-based validation on incoming or outgoing JSON payloads. This component acts as a guardrail to enforce specific content moderation rules based on configurable minimum and maximum sentence counts and JSON path expressions. -## Configure Sentence Count Guardrail +## Configure sentence count guardrail 1. In the left navigation menu, click **Develop**, then select **Policy**. @@ -37,7 +37,7 @@ This policy provides the capability to perform sentence count-based validation o 4. Save the API and Deploy the API to apply the policy to the gateway. -### Sample Sentence Count Guardrail Configuration +### Sample sentence count guardrail configuration - Guardrail Name: `Sentence Count Guardrail` - Minimum Sentence Count: `1` @@ -46,7 +46,7 @@ This policy provides the capability to perform sentence count-based validation o - Invert the Guardrail Decision: `false` - Show Guardrail Assessment: `true` -### Sample Payload to be intervened from the Sentence Count Guardrail +### Sample payload to be intervened from the sentence count guardrail ```json { @@ -59,7 +59,7 @@ This policy provides the capability to perform sentence count-based validation o } ``` -### Sample Response after Sentence Count Guardrail Intervention +### Sample response after sentence count guardrail intervention ```json { diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/url-guardrail.md b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/url-guardrail.md index c50316b0..f6044a4d 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/url-guardrail.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/url-guardrail.md @@ -12,11 +12,11 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# URL Guardrail +# URL guardrail This policy provides the capability to perform URL validity checks on incoming or outgoing JSON payloads. This component acts as a guardrail to enforce content safety by validating embedded URLs for accessibility or DNS resolution. -## Configure URL Guardrail +## Configure URL guardrail 1. In the left navigation menu, click **Develop**, then select **Policy**. @@ -36,7 +36,7 @@ The following table lists and describes the configuration parameters available f 4. Save the API and Deploy the API to apply the policy to the gateway. -### Sample URL Guardrail Configuration +### Sample URL guardrail configuration - Guardrail Name: `URL Guardrail` - Perform DNS Lookup: `false` @@ -44,7 +44,7 @@ The following table lists and describes the configuration parameters available f - JSON Path: `$.messages[0].content` - Show Guardrail Assessment: `true` -### Sample Payload to be intervened from the URL Guardrail +### Sample payload to be intervened from the URL guardrail ```json { @@ -57,7 +57,7 @@ The following table lists and describes the configuration parameters available f } ``` -### Sample Response after URL Guardrail Intervention +### Sample response after URL guardrail intervention ```json { diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/word-count-guardrail.md b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/word-count-guardrail.md index 2191edd3..61a749b5 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/word-count-guardrail.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/word-count-guardrail.md @@ -12,11 +12,11 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Word Count Guardrail +# Word count guardrail This policy provides the capability to perform word count-based validation on incoming or outgoing JSON payloads. This component acts as a guardrail to enforce specific content moderation rules based on configurable minimum and maximum word counts and JSON path expressions. -## Configure Word Count Guardrail +## Configure word count guardrail 1. In the left navigation menu, click **Develop**, then select **Policy**. @@ -37,7 +37,7 @@ This policy provides the capability to perform word count-based validation on in 4. Save the API and Deploy the API to apply the policy to the gateway. -### Sample Word Count Guardrail Configuration +### Sample word count guardrail configuration - Guardrail Name: `Word Count Guardrail` - Minimum Word Count: `2` @@ -46,7 +46,7 @@ This policy provides the capability to perform word count-based validation on in - Invert the Guardrail Decision: `false` - Show Guardrail Assessment: `true` -### Sample Payload to be intervened from the Word Count Guardrail +### Sample payload to be intervened from the word count guardrail ```json { @@ -59,7 +59,7 @@ This policy provides the capability to perform word count-based validation on in } ``` -### Sample Response after Word Count Guardrail Intervention +### Sample response after word count guardrail intervention ```json { diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/third-party-guardrail-integrations/aws-bedrock-guardrail.md b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/third-party-guardrail-integrations/aws-bedrock-guardrail.md index 7a778c0c..578875c3 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/third-party-guardrail-integrations/aws-bedrock-guardrail.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/third-party-guardrail-integrations/aws-bedrock-guardrail.md @@ -13,11 +13,11 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# AWS Bedrock Guardrail +# AWS Bedrock guardrail This policy provides the capability to integrate with [AWS Bedrock Guardrails](https://aws.amazon.com/bedrock/guardrails/) to enable real-time content safety validation and PII protection for AI applications. Through the configured Bedrock Guardrail, it can detect and block harmful content (hate speech, sexual content, self-harm, violence) and mask or redact Personally Identifiable Information (PII) in both request and response payloads. This integration helps ensure AI applications meet safety standards and compliance requirements while protecting against malicious prompt injection attacks. -## Configure AWS Bedrock Guardrail +## Configure AWS Bedrock guardrail 1. In the left navigation menu, click **Develop**, then select **Policy**. @@ -49,7 +49,7 @@ This policy provides the capability to integrate with [AWS Bedrock Guardrails](h !!! note "PII Unmasking with AWS Bedrock Guardrail" If you want to use the AWS Bedrock Guardrail for PII unmasking, you must attach the policy to both the request and response flows. This allows the policy to mask PII in the request and unmask it in the response. Moreover, the `Redact PII` option should be disabled in both flows to allow the PII to be restored in the response. If you enable `Redact PII` in the response flow, the PII will be permanently redacted and not restored. -### Sample AWS Bedrock Guardrail Configuration +### Sample AWS Bedrock guardrail configuration - Guardrail Name: `AWS Bedrock Guardrail` - AWS Guardrail ID: `guardrail-1234567890abcdef` @@ -66,7 +66,7 @@ This policy provides the capability to integrate with [AWS Bedrock Guardrails](h - Passthrough On Error: `false` - Show Guardrail Assessment: `true` -### Sample Payload to be intervened from the AWS Bedrock Guardrail +### Sample payload to be intervened from the AWS Bedrock guardrail ```json { @@ -79,7 +79,7 @@ This policy provides the capability to integrate with [AWS Bedrock Guardrails](h } ``` -### Sample Response after AWS Bedrock Guardrail Intervention +### Sample response after AWS Bedrock guardrail intervention ```json { diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/third-party-guardrail-integrations/azure-content-safety-content-moderation.md b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/third-party-guardrail-integrations/azure-content-safety-content-moderation.md index 51a18f61..ddd8ee0d 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/third-party-guardrail-integrations/azure-content-safety-content-moderation.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/guardrails/third-party-guardrail-integrations/azure-content-safety-content-moderation.md @@ -13,11 +13,11 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Azure Content Safety Content Moderation +# Azure Content Safety content moderation This policy provides the capability to integrate [Azure Content Safety Content Moderation Service](https://learn.microsoft.com/en-us/rest/api/contentsafety/text-operations/analyze-text?view=rest-contentsafety-2024-09-01&tabs=HTTP) to filter out harmful content in request bodies and AI-generated responses. This guardrail checks for hate speech, sexual content, self-harm, and violence, and can be applied to both requests and responses. -## Configure Azure Content Safety Content Moderation +## Configure Azure Content Safety content moderation 1. In the left navigation menu, click **Develop**, then select **Policy**. @@ -42,7 +42,7 @@ This policy provides the capability to integrate [Azure Content Safety Content M 4. Save the API and Deploy the API to apply the policy to the gateway. -### Sample Azure Content Safety Content Moderation Configuration +### Sample Azure Content Safety content moderation configuration - Guardrail Name: `Azure Content Safety Guardrail` - Azure Content Safety Endpoint: `https://.cognitiveservices.azure.com` @@ -55,7 +55,7 @@ This policy provides the capability to integrate [Azure Content Safety Content M - Passthrough On Error: `false` - Show Guardrail Assessment: `true` -### Sample Payload to be intervened from the Azure Content Safety Content Moderation +### Sample payload to be intervened from the Azure Content Safety content moderation ```json { @@ -68,7 +68,7 @@ This policy provides the capability to integrate [Azure Content Safety Content M } ``` -### Sample Response after Azure Content Safety Content Moderation Intervention +### Sample response after Azure Content Safety content moderation intervention ```json { diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/import-api-contract.md b/en/docs/cloud/create-api-proxy/third-party-apis/import-api-contract.md index f82484c8..e4d8582e 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/import-api-contract.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/import-api-contract.md @@ -11,19 +11,19 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Import a Third-Party API Contract +# Import a Third-party API contract API Platform provides built-in support for multiple well-known third-party APIs through the **API Platform Marketplace**. However, if you need to create an API proxy for a third-party API that is not available in the API Platform Marketplace, you can do so by importing its API contract. -## Steps to Create an API Proxy by Importing an API Contract +## Steps to create an API proxy by importing an API contract Follow these steps to create an API proxy for a third-party API by importing its API contract: -### 1. Access the API Platform Console +### 1. Access the API Platform console 1. Sign in to the [API Platform Console](https://console.bijira.dev/) and select your project. -### 2. Import the API Contract +### 2. Import the API contract 1. Click **+Create**. 2. Navigate to **Create an API Proxy for Third-Party APIs (Egress)** and click **Import API Contract**. @@ -34,7 +34,7 @@ Follow these steps to create an API proxy for a third-party API by importing its - Import from SwaggerHub 4. Click **Next**. -### 3. Configure API Proxy Details +### 3. Configure API proxy details 1. Update the required API proxy details, including: - API Name @@ -46,12 +46,12 @@ Follow these steps to create an API proxy for a third-party API by importing its Once created, the overview page of the new API proxy appears. -### 4. Configure Backend Settings +### 4. Configure backend settings 1. In the left navigation menu, click **Develop**, then select **Policy**. 2. Depending on the third-party API requirements, configure **Endpoint Configurations** or set up an **API-level mediation policy** to handle authentication and authorization. -### Next Steps +### Next steps - **Test the API proxy** to ensure it correctly forwards requests to the third-party API. See [Test REST Endpoints via the OpenAPI Console](../../test-api-proxy/openapi-console.md). - **Apply additional policies** if needed (e.g., rate limiting, security policies). See [Policy Overview](../../develop-api-proxy/policy/attach-and-manage-policies.md#attach-a-policy). diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/mistral.md b/en/docs/cloud/create-api-proxy/third-party-apis/mistral.md index 0816a6cb..eb41ac16 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/mistral.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/mistral.md @@ -13,13 +13,13 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Create an API Proxy for an Mistral AI API +# Create an API proxy for an Mistral AI API Follow the steps below to create an AI API: --- -## 1. Access the API Platform Console +## 1. Access the API Platform console 1. Sign in to the [API Platform Console](https://console.bijira.dev/) and select your project. @@ -49,7 +49,7 @@ Follow the steps below to create an AI API: --- -## 3. Configure Backend Settings +## 3. Configure backend settings 1. In the left navigation menu, click **Develop**, then select **Policy**. @@ -68,7 +68,7 @@ Follow the steps below to create an AI API: ![Endpoint Configuration dialog showing Mistral endpoint URL with Authorization header and Bearer token API key fields](../../../assets/img/create-api-proxy/third-party-apis/ai-apis/mistral-key.png) -## 4. Deploy to development and Production Environments +## 4. Deploy to development and production environments 1. In the left navigation menu, click **Deploy**, Deploy to Development environment @@ -82,7 +82,7 @@ Follow the steps below to create an AI API: --- -## Next Steps +## Next steps - **Test the AI API** to ensure it correctly forwards requests to the AI service. See [Test REST Endpoints via the OpenAPI Console](../../test-api-proxy/openapi-console.md). diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/open-ai.md b/en/docs/cloud/create-api-proxy/third-party-apis/open-ai.md index 5d73020e..81d48eac 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/open-ai.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/open-ai.md @@ -13,13 +13,13 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Create an API Proxy for an Open AI API +# Create an API proxy for an Open AI API Follow the steps below to create an AI API: --- -## 1. Access the API Platform Console +## 1. Access the API Platform console 1. Sign in to the [API Platform Console](https://console.bijira.dev/) and select your project. @@ -49,7 +49,7 @@ Follow the steps below to create an AI API: --- -## 3. Configure Backend Settings +## 3. Configure backend settings 1. In the left navigation menu, click **Develop**, then select **Policy**. @@ -68,7 +68,7 @@ Follow the steps below to create an AI API: ![Endpoint Configuration dialog showing OpenAI endpoint URL with empty API Key Header and API Key input fields](../../../assets/img/create-api-proxy/third-party-apis/ai-apis/openai-endpoint-config.png) -## 4. Deploy to development and Production Environments +## 4. Deploy to development and production environments 1. In the left navigation menu, click **Deploy**, Deploy to Development environment @@ -82,7 +82,7 @@ Follow the steps below to create an AI API: --- -## Next Steps +## Next steps - **Test the AI API** to ensure it correctly forwards requests to the AI service. See [Test REST Endpoints via the OpenAPI Console](../../test-api-proxy/openapi-console.md). diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/semantic-cache.md b/en/docs/cloud/create-api-proxy/third-party-apis/semantic-cache.md index 0f71b3e7..3ba1d4de 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/semantic-cache.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/semantic-cache.md @@ -13,12 +13,12 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Semantic Caching +# Semantic caching AI services frequently involve repetitive queries, leading to unnecessary token usage and increased latency. API Platform’s AI Gateway introduces semantic caching, allowing responses to similar requests to be cached and reused intelligently, minimizing redundant processing, improving response times, and reducing overall costs. -## Configure Semantic Caching Policy +## Configure semantic caching policy 1. In the left navigation menu, click **Develop**, then select **Policy**. @@ -52,7 +52,7 @@ The configurable fields of the above policy have been described below. | `Password` | Password for the specified database user. | `securepassword123` | | `Database` | Index of the vector database to connect to. | `0` | -## Sample Payloads and Responses +## Sample payloads and responses First Request: @@ -115,7 +115,7 @@ Second Request: -## Next Steps +## Next steps - **Verify** it is properly redeployed to ensure the policy and the configurations are properly applied. diff --git a/en/docs/cloud/create-api-proxy/third-party-apis/token-ratelimit.md b/en/docs/cloud/create-api-proxy/third-party-apis/token-ratelimit.md index a99e2e61..880d731a 100644 --- a/en/docs/cloud/create-api-proxy/third-party-apis/token-ratelimit.md +++ b/en/docs/cloud/create-api-proxy/third-party-apis/token-ratelimit.md @@ -18,7 +18,7 @@ content_type: "how-to" AI services often incur costs on a per-token basis, making usage control critical. API Platform’s AI Gateway introduces token-based rate limiting that can be applied at the API level. -## Configure Token Based Ratelimit Policy +## Configure token based ratelimit policy 1. In the left navigation menu, click **Develop**, then select **Policy**. diff --git a/en/docs/cloud/develop-api-proxy/authentication-and-authorization/pass-end-user-attributes-to-upstream-services.md b/en/docs/cloud/develop-api-proxy/authentication-and-authorization/pass-end-user-attributes-to-upstream-services.md index 44666c77..d7ce841e 100644 --- a/en/docs/cloud/develop-api-proxy/authentication-and-authorization/pass-end-user-attributes-to-upstream-services.md +++ b/en/docs/cloud/develop-api-proxy/authentication-and-authorization/pass-end-user-attributes-to-upstream-services.md @@ -1,4 +1,4 @@ -# Pass End-User Attributes to Upstream Services +# Pass end-user attributes to upstream services There are scenarios where a backend service needs to apply specific logic or make decisions depending on the user consuming an API. In such scenarios, you must pass end-user attributes to the backend during an API call. diff --git a/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-asgardeo.md b/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-asgardeo.md index a7b83705..23a0822a 100644 --- a/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-asgardeo.md +++ b/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-asgardeo.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Secure API Access with Asgardeo +# Secure API access with Asgardeo API security refers to the measures and practices used to protect Application Programming Interfaces (APIs) from potential threats and vulnerabilities. APIs are essential for enabling communication and data exchange between different software applications and services, making them a critical component in modern software development. However, their openness and accessibility can also make them targets for various security risks. Authentication and authorization are key aspects of API security. Authentication is ensuring that only authorized users or applications can access the API. This can involve using API keys, tokens, or more advanced authentication methods like OAuth 2.0. Authorization is controlling what authenticated users or applications are allowed to do within the API. Authorization mechanisms restrict access to specific resources and actions based on user roles or permissions. diff --git a/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-azure-ad.md b/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-azure-ad.md index ab1993b4..cbfd9e44 100644 --- a/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-azure-ad.md +++ b/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-azure-ad.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Secure API Access with Microsoft Azure Active Directory (Azure AD) +# Secure API access with Microsoft Azure Active Directory (Azure AD) API security refers to the measures and practices used to protect Application Programming Interfaces (APIs) from potential threats and vulnerabilities. Authentication and authorization are key aspects of API security. Authentication is ensuring that only authorized users or applications can access the API. This can involve using API keys, tokens, or more advanced authentication methods like OAuth 2.0. Authorization is controlling what authenticated users or applications are allowed to do within the API. Authorization mechanisms restrict access to specific resources and actions based on user roles or permissions. diff --git a/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-bijira-sts.md b/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-bijira-sts.md index 5c88ee06..7b212da2 100644 --- a/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-bijira-sts.md +++ b/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-bijira-sts.md @@ -12,11 +12,11 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Secure API Access with API Platform STS +# Secure API access with API Platform STS API security refers to the measures and practices used to protect Application Programming Interfaces (APIs) from potential threats and vulnerabilities. APIs are essential for enabling communication and data exchange between different software applications and services, making them a critical component in modern software development. However, their openness and accessibility can also make them targets for various security risks. Authentication and authorization are key aspects of API security. Authentication is ensuring that only authorized users or applications can access the API. This can involve using API keys, tokens, or more advanced authentication methods like OAuth 2.0. Authorization is controlling what authenticated users or applications are allowed to do within the API. Authorization mechanisms restrict access to specific resources and actions based on user roles or permissions. -API Platform's built-in Secure Token Service (STS) can seamlessly integrate with API Platform APIs to provide authentication and authorization. This guide will walk you through setting up API Platform STS to authenticate API invocations. +API Platform's built-in Secure Token Service (STS) can seamlessly integrates with API Platform APIs to provide authentication and authorization. This guide will walk you through setting up API Platform STS to authenticate API invocations. This guide walks you through the following steps: diff --git a/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-external-idp.md b/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-external-idp.md index 477e154d..de69c0c2 100644 --- a/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-external-idp.md +++ b/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-external-idp.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Secure API Access with an External Key Manager +# Secure API access with an external key manager API security refers to the measures and practices used to protect Application Programming Interfaces (APIs) from potential threats and vulnerabilities. APIs are essential for enabling communication and data exchange between different software applications and services, making them a critical component in modern software development. However, their openness and accessibility can also make them targets for various security risks. Authentication and authorization are key aspects of API security. Authentication is ensuring that only authorized users or applications can access the API. This can involve using API keys, tokens, or more advanced authentication methods like OAuth 2.0. Authorization is controlling what authenticated users or applications are allowed to do within the API. Authorization mechanisms restrict access to specific resources and actions based on user roles or permissions. diff --git a/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-communication-between-bijira-gateway-and-backend-with-oauth2.md b/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-communication-between-bijira-gateway-and-backend-with-oauth2.md index 3a0f9406..7a5132b0 100644 --- a/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-communication-between-bijira-gateway-and-backend-with-oauth2.md +++ b/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-communication-between-bijira-gateway-and-backend-with-oauth2.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Secure Communication Between the API Platform Gateway and Your Backend with OAuth2 +# Secure communication between the API Platform gateway and your backend with OAuth2 OAuth2 is an industry-standard authorization framework that enables secure, delegated access to protected resources without exposing user credentials. By issuing scoped access tokens, OAuth2 ensures that clients can authenticate to backend services in a controlled, auditable manner. @@ -22,9 +22,9 @@ When you need the API Platform Gateway to call your backend over OAuth2, use the ### Prerequisites -- **Protected Backend**: The target endpoint must enforce OAuth2 (e.g., bearer-token validation). -- **Token Endpoint**: The URL of the Key manager's token endpoint that protects your backend. -- **OAuth2 Application Credentials**: A client ID and secret for an OAuth2 application dedicated to the API Platform Gateway's outbound calls. +- **Protected backend**: The target endpoint must enforce OAuth2 (e.g., bearer-token validation). +- **Token endpoint**: The URL of the Key manager's token endpoint that protects your backend. +- **OAuth2 application credentials**: A client ID and secret for an OAuth2 application dedicated to the API Platform Gateway's outbound calls. !!! note Only the client-credentials grant type is currently supported. diff --git a/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-communication-between-the-bijira-gateway-and-your-backend-with-mutual-tls.md b/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-communication-between-the-bijira-gateway-and-your-backend-with-mutual-tls.md index e51292a7..c41d4c32 100644 --- a/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-communication-between-the-bijira-gateway-and-your-backend-with-mutual-tls.md +++ b/en/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-communication-between-the-bijira-gateway-and-your-backend-with-mutual-tls.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Secure Communication Between the API Platform Gateway and Your Backend with Mutual TLS +# Secure communication between the API Platform gateway and your backend with mutual TLS To establish secure communication between the API Platform Gateway and your backend, you can configure mutual TLS. diff --git a/en/docs/cloud/develop-api-proxy/documents.md b/en/docs/cloud/develop-api-proxy/documents.md index d98bcc7e..3df6dd40 100644 --- a/en/docs/cloud/develop-api-proxy/documents.md +++ b/en/docs/cloud/develop-api-proxy/documents.md @@ -23,7 +23,7 @@ When an API consumer signs in to the API Platform Developer Portal to browse API To provide such information that improves the overall visibility of the API, an API developer can add such documentation to an API before publishing it to the Developer Portal. -## Add Documents to an API +## Add documents to an API To add documentation for an API, follow the steps given below. diff --git a/en/docs/cloud/develop-api-proxy/lifecycle-management.md b/en/docs/cloud/develop-api-proxy/lifecycle-management.md index a9572320..0776f50d 100644 --- a/en/docs/cloud/develop-api-proxy/lifecycle-management.md +++ b/en/docs/cloud/develop-api-proxy/lifecycle-management.md @@ -12,13 +12,13 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Lifecycle Management +# Lifecycle management API lifecycle management is an important aspect of API management. The API lifecycle consists of various states that an API passes through, from creation to retirement. In API Platform, there are six distinct lifecycle states: created, pre-released, published, deprecated, and retired. By leveraging the various lifecycle states, API managers can optimize the development process and ensure that subscribers have access to the latest and most reliable APIs. -## API Lifecycle States +## API lifecycle states The following lifecycle states are applicable to APIs in API Platform: @@ -30,7 +30,7 @@ The following lifecycle states are applicable to APIs in API Platform: | **DEPRECATED** | The old version of an API is moved to this state when a newer version of the API is PUBLISHED.| The API is deployed and is available to existing subscribers. New subscriptions are disabled. Existing subscribers can continue to use it as usual until the API is retired.| | **RETIRED** | The API is no longer in use when it is in this state.| The API is unpublished and deleted from the Developer Portal.| -## Manage the Lifecycle of an API +## Manage the lifecycle of an API To change the lifecycle state of an API via the API Platform Console, follow the instructions given below: diff --git a/en/docs/cloud/develop-api-proxy/make-api-ai-ready.md b/en/docs/cloud/develop-api-proxy/make-api-ai-ready.md index 3ea4dad7..310aef52 100644 --- a/en/docs/cloud/develop-api-proxy/make-api-ai-ready.md +++ b/en/docs/cloud/develop-api-proxy/make-api-ai-ready.md @@ -12,14 +12,14 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Make an API AI-Ready +# Make an API AI-ready When you publish an API to the Developer Portal, it is automatically included in the portal's machine readable surfaces including `llms.txt`, the API catalog Markdown, and per API documentation endpoints. These surfaces are what AI agents use to discover, understand, and invoke your APIs. This page explains what you can do as an API publisher to make your API as useful as possible for AI agents. -## Write a Clear API Description +## Write a clear API description The API description is the primary signal an AI agent uses to decide whether an API is relevant to the task it is trying to accomplish. A vague or empty description leads to missed discovery or incorrect usage. @@ -31,7 +31,7 @@ The API description is the primary signal an AI agent uses to decide whether an The description appears in `llms.txt` and in the agent-readable API catalog (`apis.md`), so it is often the first thing an agent reads about your API. -## Use a Well-Structured API Specification +## Use a well-structured API specification Publishing a complete, accurate API specification is one of the most impactful things you can do for AI discoverability. @@ -44,7 +44,7 @@ For REST APIs, follow these practices in your OpenAPI spec to improve agent accu - Note any authentication requirements per operation -## Add Supporting Documents +## Add supporting documents Beyond the machine readable specification, you can attach prose documents to your API (see [Documents](documents.md)). These documents are surfaced to agents in the per API Markdown endpoint alongside the specification. @@ -58,7 +58,7 @@ Use documents to cover things the specification cannot express well: Well written prose documents reduce the chance that an agent will misinterpret the specification or hallucinate behavior that doesn't exist. -## Control Agent Visibility +## Control agent visibility All published APIs are agent visible by default. If an API should not be surfaced to AI agents, for example, an internal API not intended for external consumption you can hide it from agent facing endpoints while keeping it accessible to human users in the portal. @@ -78,7 +78,7 @@ Once hidden, the API is excluded from `llms.txt`, `apis.md`, and all per API Mar !!! note This setting applies per API. Hiding one API does not affect the visibility of others. -## Publish API Workflows +## Publish API workflows If your API is used in multi-step scenarios, for example, authenticate, then create a resource, then retrieve it, consider publishing an API Workflow that guides agents through the correct sequence of calls. @@ -86,7 +86,7 @@ Workflows solve a common agent failure mode: left to reason freely, agents often API Workflows are managed by portal admins. See [Managing API Workflows](../devportal/admin-settings/managing-api-workflows.md) for details. -## Verify AI Discoverability +## Verify AI discoverability After publishing your API, you can verify that it appears correctly in the portal's agent-facing surfaces: @@ -94,7 +94,7 @@ After publishing your API, you can verify that it appears correctly in the porta 2. Fetch `/{orgName}/views/{viewName}/api/{apiHandle}.md` and confirm the Markdown documentation is complete and readable. 3. Fetch `/{orgName}/views/{viewName}/api/{apiHandle}/docs/specification.json` (or `.graphql` / `.xml` depending on your API type) and confirm the specification is valid. -## What's Next +## What's next - [Managing API Workflows](../devportal/admin-settings/managing-api-workflows.md) — publish workflows that guide agents through multi-step call sequences - [LLM Instructions](../devportal/admin-settings/llm-instructions.md) — add portal-level context that applies across all APIs in `llms.txt` diff --git a/en/docs/cloud/develop-api-proxy/policy/attach-and-manage-policies.md b/en/docs/cloud/develop-api-proxy/policy/attach-and-manage-policies.md index b6d46c75..203392f5 100644 --- a/en/docs/cloud/develop-api-proxy/policy/attach-and-manage-policies.md +++ b/en/docs/cloud/develop-api-proxy/policy/attach-and-manage-policies.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Attach and Manage Policies +# Attach and manage policies You can easily attach one or more policies to an API proxy component implementation via the API Platform Console. If necessary, you can also rearrange or swap the policies you attach. @@ -36,9 +36,9 @@ When a mediation policy is attached to a specific flow, the API invocation under - If an error occurs during the execution of policies or due to an internal error, API Platform executes the `Error` flow and sends an error response to the client. -## Attach a Policy +## Attach a policy -### Attach an API level Policy +### Attach an API level policy To attach an API level policy to the `Request` flow of a REST API proxy, follow the steps given below: @@ -53,7 +53,7 @@ To attach an API level policy to the `Request` flow of a REST API proxy, follow ![Configure Pass User Context to Backend policy panel with End User Token Audiences input field](../../../assets/img/develop-api-proxy/policy/configure-policy-API-level.png) 7. Click **Add** to attach the policy. Then, click **Save** to apply the configuration to the API. -### Attach a Resource level Policy +### Attach a resource level policy To attach a resource level policy to the `Request`, `Response`, or `Error` flow of a REST API proxy, follow the steps given below: @@ -84,7 +84,7 @@ To deploy the API follow the steps below: 3. Click **Save & Deploy**. -## Refresh Mediation Policies +## Refresh mediation policies API Platform selectively generates and builds the mediation application code during component deployment depending on specific changes. These changes include: diff --git a/en/docs/cloud/develop-api-proxy/policy/overview.md b/en/docs/cloud/develop-api-proxy/policy/overview.md index a13a6658..bf034fa1 100644 --- a/en/docs/cloud/develop-api-proxy/policy/overview.md +++ b/en/docs/cloud/develop-api-proxy/policy/overview.md @@ -18,7 +18,7 @@ API Platform simplifies the design, management, and mediation of API proxies wit You can intuitively map API proxies to service contracts with API Platform's interactive UI, ensuring clear and consistent request routing to backend services. With built-in mediation policies, API Platform provides flexibility to manage API requests and responses, facilitating custom transformations and logic without requiring custom code. This enhances API manageability, making it easier to configure, update, and control API traffic within the platform. -## Designing API Proxies +## Designing API proxies You can further redesign and customize your API proxy created from following the [Create API Proxy](../../create-api-proxy/overview.md) flow. diff --git a/en/docs/cloud/develop-api-proxy/policy/policies.md b/en/docs/cloud/develop-api-proxy/policy/policies.md index 22916683..c05ca40d 100644 --- a/en/docs/cloud/develop-api-proxy/policy/policies.md +++ b/en/docs/cloud/develop-api-proxy/policy/policies.md @@ -18,29 +18,29 @@ Policies are units of business logic that you can apply to modify the flow of AP You can apply a policy in API or resource level to alter the `Request`, `Response`, or `Error` flow of an API invocation before it reaches the backend or the client. For example, you can add a policy to the response flow to transform the payload from JSON to XML and add a header to the response. -## Inbuilt Mediation Policies +## Inbuilt mediation policies API Platform supports a set of inbuilt mediation policies that can handle common API transformation and mediation tasks. These policies run within a single mediation service, making it straightforward to implement and manage complex mediation logic. The following inbuilt policies are available in API Platform at API level and resource level: -### API-level Policies +### API-level policies - **OAuth2**: Secures an API by enforcing OAuth 2.0 authentication. This policy ensures that only authenticated clients with valid access tokens can access the API. The security header is configurable at the API level. This policy is enabled by default for every API resource, and can be disabled for individual resources by removing from the flow as necessary. -- **Pass User Context to Backend**: Forwards user-related information to the backend service under the header `x-jwt-assertion`. This policy ensures that user identity details are included in the request sent to the backend. In addition users can set end user token audiences. It is useful for enforcing authorization, logging, or customizing responses based on the authenticated user. This policy is only applicable at the API level. -- **Rate Limiting**: Restricts the number of API requests a client can make within a defined time window. Users can configure limits based on request count and time unit (e.g. 100 requests per minute). When the limit is exceeded, further requests are rejected with a `429 Too Many Requests` response. Users are able to set rate limiting thresholds at both API level and resource level. -- **CORS (Cross-Origin Resource Sharing)**: Controls how resources on an API can be accessed from different origins. This policy allows users to configure `Access-Control-Allow-Origin`, `Access-Control-Allow-Headers`, `Access-Control-Allow-Methods`, and `Access-Control-Allow-Credentials`. It ensures secure and flexible cross-origin requests, enabling APIs to be accessed from web applications running on different domains. This policy is only applicable at the API level. +- **Pass user context to backend**: Forwards user-related information to the backend service under the header `x-jwt-assertion`. This policy ensures that user identity details are included in the request sent to the backend. In addition users can set end user token audiences. It is useful for enforcing authorization, logging, or customizing responses based on the authenticated user. This policy is only applicable at the API level. +- **Rate limiting**: Restricts the number of API requests a client can make within a defined time window. Users can configure limits based on request count and time unit (e.g. 100 requests per minute). When the limit is exceeded, further requests are rejected with a `429 Too Many Requests` response. Users are able to set rate limiting thresholds at both API level and resource level. +- **CORS (Cross-origin resource sharing)**: Controls how resources on an API can be accessed from different origins. This policy allows users to configure `Access-Control-Allow-Origin`, `Access-Control-Allow-Headers`, `Access-Control-Allow-Methods`, and `Access-Control-Allow-Credentials`. It ensures secure and flexible cross-origin requests, enabling APIs to be accessed from web applications running on different domains. This policy is only applicable at the API level. -### Resource-level Policies +### Resource-level policies - **JSON to XML**: Transforms a request/response with a JSON payload to a request/response with an XML payload. This is only applicable to the request flow and response flow mediation sequences. This policy assumes that the request/response payload is JSON. Attempting to use it on a request/response with a non-JSON payload will result in premature termination of the mediation flow. For the same reason, this policy cannot be attached multiple times to a resource since once it is used, the payload will be an XML value. - **XML to JSON**: Transforms a request/response with an XML payload to a request/response with a JSON payload. This policy assumes that the request/response payload is XML. Attempting to use it on a request/response with a non-XML payload will result in premature termination of the mediation flow. For the same reason, this policy cannot be attached multiple times to a resource since once it is used, the payload will be a JSON value. -- **Remove Query Parameter**: Removes specified query parameters from a request. You can use this policy multiple times to remove different parameters. Attempting to remove a non-existent parameter has no effect. If the parameter exists, it will be removed; otherwise, the request proceeds as usual. -- **Remove Header**: Removes specified headers from a request or response. You can attach this policy multiple times to remove multiple headers. The header name must be static, but you can use placeholders to configure different values for different environments. For example, `${headerName}`. -- **Add Query Parameter**: Adds query parameters to a request. You can attach this policy multiple times to add various parameters. Adding the same parameter multiple times creates an array of values. The parameter name and value must be static, but you can use placeholders to configure different values for different environments. For example, `${fooValue}`. -- **Add Header**: Adds headers to a request or response. If the same header is added multiple times, values are appended rather than overwritten. The header name and value must be static, but you can use placeholders to configure different values for different environments. For example, `${authzHeaderValue}`. -- **Set Header**: Sets headers in a request or response, overwriting any existing values. You can attach this policy multiple times to set multiple headers. Each time the same header is set, it replaces the previous value. The header name and value must be static, but you can use placeholders to configure different values for different environments. For example, `${authzHeaderValue}`. -- **Rewrite Resource Path**: Modifies the resource path of an HTTP request by replacing the original path with a new relative path. You can apply this policy multiple times, but only the last instance will take effect. The new path must be static, but you can use placeholders to configure different values for different environments. For example, `${myResourcePath}`. -- **Log Message**: Logs the payload and headers of a request or response. Attaching this policy multiple times results in duplicate log entries. By default, headers and payloads are not logged. To log them, you can enable `Log Headers` and `Log Payload` parameters. To exclude specific headers when logging, you can use the `Excluded Headers` parameter, which takes a comma-separated list of header names. An error will occur if payload logging is enabled but the payload cannot be read. -- **Permissions (Scopes)**: Defines fine-grained access control by assigning permissions (scopes) to API resources. Each resource can have one or more scopes, and only users or applications with the required scope in their access token can invoke the resource. +- **Remove query parameter**: Removes specified query parameters from a request. You can use this policy multiple times to remove different parameters. Attempting to remove a non-existent parameter has no effect. If the parameter exists, it will be removed; otherwise, the request proceeds as usual. +- **Remove header**: Removes specified headers from a request or response. You can attach this policy multiple times to remove multiple headers. The header name must be static, but you can use placeholders to configure different values for different environments. For example, `${headerName}`. +- **Add query parameter**: Adds query parameters to a request. You can attach this policy multiple times to add various parameters. Adding the same parameter multiple times creates an array of values. The parameter name and value must be static, but you can use placeholders to configure different values for different environments. For example, `${fooValue}`. +- **Add header**: Adds headers to a request or response. If the same header is added multiple times, values are appended rather than overwritten. The header name and value must be static, but you can use placeholders to configure different values for different environments. For example, `${authzHeaderValue}`. +- **Set header**: Sets headers in a request or response, overwriting any existing values. You can attach this policy multiple times to set multiple headers. Each time the same header is set, it replaces the previous value. The header name and value must be static, but you can use placeholders to configure different values for different environments. For example, `${authzHeaderValue}`. +- **Rewrite resource path**: Modifies the resource path of an HTTP request by replacing the original path with a new relative path. You can apply this policy multiple times, but only the last instance will take effect. The new path must be static, but you can use placeholders to configure different values for different environments. For example, `${myResourcePath}`. +- **Log message**: Logs the payload and headers of a request or response. Attaching this policy multiple times results in duplicate log entries. By default, headers and payloads are not logged. To log them, you can enable `Log headers` and `Log payload` parameters. To exclude specific headers when logging, you can use the `Excluded headers` parameter, which takes a comma-separated list of header names. An error will occur if payload logging is enabled but the payload cannot be read. +- **Permissions (scopes)**: Defines fine-grained access control by assigning permissions (scopes) to API resources. Each resource can have one or more scopes, and only users or applications with the required scope in their access token can invoke the resource. These inbuilt mediation policies provide flexibility to manage API requests and responses, allowing for custom transformations and logic without requiring custom code. diff --git a/en/docs/cloud/develop-api-proxy/subscription-plans.md b/en/docs/cloud/develop-api-proxy/subscription-plans.md index 576a9ae3..2a76c765 100644 --- a/en/docs/cloud/develop-api-proxy/subscription-plans.md +++ b/en/docs/cloud/develop-api-proxy/subscription-plans.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Assign Subscription Plans to APIs +# Assign subscription plans to APIs API subscription plans allow API publishers to control and manage access to APIs. These plans define the rules, limitations, and pricing for how clients can interact with APIs, ensuring efficient resource utilization and robust security. diff --git a/en/docs/cloud/devportal/admin-settings/llm-instructions.md b/en/docs/cloud/devportal/admin-settings/llm-instructions.md index c31fcec8..63cab376 100644 --- a/en/docs/cloud/devportal/admin-settings/llm-instructions.md +++ b/en/docs/cloud/devportal/admin-settings/llm-instructions.md @@ -1,10 +1,10 @@ -# LLM Instructions +# LLM instructions LLM Instructions allow portal admins to provide AI agents with high level context about the developer portal, what APIs are available, how the portal is organized, and any conventions or constraints agents should follow when interacting with it. These instructions are published as part of the portal's `llms.txt` file, which is the primary entry point for AI agents discovering the portal's capabilities. -## What Are LLM Instructions? +## What are LLM instructions? LLM Instructions are free form natural language text written by the portal admin. They appear at the top of `llms.txt` and are read by agents before they navigate the rest of the portal's content. @@ -19,7 +19,7 @@ Use this space to tell agents: Well written LLM instructions reduce agent errors and improve the quality of AI-assisted integrations by giving agents the orientation they need upfront, rather than leaving them to infer context from individual API specs. -## Configuring LLM Instructions +## Configuring LLM instructions LLM Instructions are configured at the portal (view) level in the admin settings. @@ -32,7 +32,7 @@ LLM Instructions are configured at the portal (view) level in the admin settings Changes take effect immediately, the updated instructions are reflected in `llms.txt` as soon as you save. -## Previewing the Output +## Previewing the output To verify how your instructions appear to agents, fetch the portal's `llms.txt` directly: diff --git a/en/docs/cloud/devportal/admin-settings/managing-api-workflows.md b/en/docs/cloud/devportal/admin-settings/managing-api-workflows.md index 6ce27177..0443b247 100644 --- a/en/docs/cloud/devportal/admin-settings/managing-api-workflows.md +++ b/en/docs/cloud/devportal/admin-settings/managing-api-workflows.md @@ -1,9 +1,9 @@ -# Managing API Workflows +# Managing API workflows As a portal admin, you can create, edit, publish, and control the visibility of API Workflows. This page covers the full workflow lifecycle from an admin perspective. -## Creating a Workflow +## Creating a workflow 1. In the Developer Portal, navigate to **Admin - Settings** and select the portal. 2. Open the **API Workflows** section. @@ -14,16 +14,16 @@ As a portal admin, you can create, edit, publish, and control the visibility of |---|---| | **Name** | A short, task-oriented name (e.g., "Place an Order", "Register a Webhook") | | **Description** | One to two sentences explaining the goal of the workflow and when to use it | -| **Arazzo Specification** | The machine readable workflow definition in Arazzo format | -| **Agent Prompt** | Natural language guidance for AI agents on when and how to invoke the workflow | -| **Agent Visibility** | Controls whether the workflow is surfaced to AI agents. Set to **Visible** to include it in `llms.txt` and `api-workflows.md`, or **Hidden** to exclude it from agent facing surfaces while keeping it accessible to human users in the portal | +| **Arazzo specification** | The machine readable workflow definition in Arazzo format | +| **Agent prompt** | Natural language guidance for AI agents on when and how to invoke the workflow | +| **Agent visibility** | Controls whether the workflow is surfaced to AI agents. Set to **Visible** to include it in `llms.txt` and `api-workflows.md`, or **Hidden** to exclude it from agent facing surfaces while keeping it accessible to human users in the portal | ![API workflow creation form showing Basic info step with Name, Description, Portal visibility, and Agent visibility fields](../../../assets/img/devportal/api-workflow-creation.png) 5. Click **Save as Draft** to save without publishing, or **Publish** to make the workflow live immediately. -## Editing a Workflow +## Editing a workflow 1. Navigate to **API Workflows** in the admin settings. 2. Select the workflow you want to edit. @@ -31,7 +31,7 @@ As a portal admin, you can create, edit, publish, and control the visibility of 4. Click **Save** to update a published workflow, or **Save as Draft** to unpublish it while editing. -## Publishing and Unpublishing +## Publishing and unpublishing Workflows must be explicitly published to become visible to consumers. Draft workflows are only visible within the admin console. @@ -46,18 +46,18 @@ To unpublish: 2. Click **Unpublish** (or **Save as Draft**). The workflow is removed from the portal and from `llms.txt` / `api-workflows.md` immediately. -## Controlling Visibility +## Controlling visibility Visibility is controlled independently for human users and AI agents. -### Portal UI Visibility +### Portal UI visibility Determines whether the workflow appears in the developer portal for human users. - **Visible** — appears in the portal's API Workflows section and in search results - **Hidden** — not shown in the portal UI; still accessible via direct URL if the consumer has the handle -### Agent Visibility +### Agent visibility Determines whether the workflow is exposed to AI agents via machine readable surfaces. diff --git a/en/docs/cloud/devportal/api-workflows/consuming-api-workflows.md b/en/docs/cloud/devportal/api-workflows/consuming-api-workflows.md index 1522b472..79cd0eee 100644 --- a/en/docs/cloud/devportal/api-workflows/consuming-api-workflows.md +++ b/en/docs/cloud/devportal/api-workflows/consuming-api-workflows.md @@ -1,8 +1,8 @@ -# Consuming API Workflows +# Consuming API workflows API Workflows are published in the developer portal as structured, reusable sequences of API calls. Once an admin publishes a workflow, it becomes available to both human developers browsing the portal and AI agents that consume the portal's machine readable surfaces. -## How Human Users Discover Workflows +## How human users discover workflows Workflows are surfaced in the **API Workflows** section of the developer portal, accessible from the main navigation. @@ -14,7 +14,7 @@ Each workflow is listed with its name and a short description that explains the ![Specialist Treatment Booking Workflow detail page with flow diagram, description, and source API links](../../../assets/img/devportal/view-api-flow.png) -## How AI Agents Discover Workflows +## How AI agents discover workflows Agents that interact with the developer portal can discover workflows through two machine readable endpoints: @@ -38,7 +38,7 @@ A dedicated Markdown document lists all agent-visible workflows in a format opti GET /{orgName}/views/{viewName}/api-workflows.md ``` -### Fetching a Specific Workflow +### Fetching a specific workflow Once an agent identifies a relevant workflow, it can fetch the full Arazzo specification and agent prompt directly: @@ -48,7 +48,7 @@ Once an agent identifies a relevant workflow, it can fetch the full Arazzo speci --- -## Workflow Visibility +## Workflow visibility Not all published workflows are visible to all consumers. Admins control visibility independently for human users and AI agents. @@ -62,7 +62,7 @@ This allows workflows to be tailored for specific audiences — for example, exp --- -## Using a Workflow as a Developer +## Using a workflow as a developer To follow a workflow: @@ -71,7 +71,7 @@ To follow a workflow: 3. Follow the steps in order, using the inputs and outputs described at each step. 4. If the workflow includes an Arazzo specification, download it to use with tools that support the Arazzo format. -## Using a Workflow as an Agent +## Using a workflow as an agent To invoke a workflow programmatically: diff --git a/en/docs/cloud/devportal/consuming-services/consume-an-api-secured-with-api-key.md b/en/docs/cloud/devportal/consuming-services/consume-an-api-secured-with-api-key.md index 3db1b8ba..abc9ca5b 100644 --- a/en/docs/cloud/devportal/consuming-services/consume-an-api-secured-with-api-key.md +++ b/en/docs/cloud/devportal/consuming-services/consume-an-api-secured-with-api-key.md @@ -1,17 +1,17 @@ -# Consume an API Secured with API Key +# Consume an API secured with API key ## Prerequisites Before proceeding, ensure you have [Created an Application](../manage-applications/create-an-application.md) and [Subscribed to an API](../manage-subscriptions/subscribe-to-an-api.md) to consume. -## Creating an API Key +## Creating an API key To consume an API secured with an API key, ensure that the desired API has API Key authentication enabled. Then create an application in the API Platform Developer Portal and subscribe it to the API under a defined usage policy. The API key will then be associated with that specific application. --- -### Steps to Create an API Key +### Steps to create an API key 1. Ensure the desired API has API Key authentication enabled. diff --git a/en/docs/cloud/devportal/consuming-services/consume-an-api-secured-with-oauth2.md b/en/docs/cloud/devportal/consuming-services/consume-an-api-secured-with-oauth2.md index 34c4d7f1..1aa7f0c7 100644 --- a/en/docs/cloud/devportal/consuming-services/consume-an-api-secured-with-oauth2.md +++ b/en/docs/cloud/devportal/consuming-services/consume-an-api-secured-with-oauth2.md @@ -1,4 +1,4 @@ -# Consume an API Secured with OAuth2 +# Consume an API secured with OAuth2 ## Prerequisites diff --git a/en/docs/cloud/devportal/developer-portal-mode.md b/en/docs/cloud/devportal/developer-portal-mode.md index 214df2da..0751f660 100644 --- a/en/docs/cloud/devportal/developer-portal-mode.md +++ b/en/docs/cloud/devportal/developer-portal-mode.md @@ -1,4 +1,4 @@ -# Developer Portal Mode +# Developer Portal mode API Platform's developer portal can be configured in different modes based on your requirements. @@ -10,4 +10,4 @@ Devportal configuration has 3 modes. 1. **API Portal** - In this mode, only API Proxies will be shown in the Devportal. Suitable if you have nothing to do with MCP. 2. **MCP Hub** - In this mode, only MCP Servers will be shown in the Devportal. Suitable if you are using API Platform for MCP related use cases. -3. **API & MCP Portal** - This is the **default** mode. Both API Proxies and MCP Servers will be shown in the Devportal \ No newline at end of file +3. **API and MCP Portal** - This is the **default** mode. Both API Proxies and MCP Servers will be shown in the Devportal \ No newline at end of file diff --git a/en/docs/cloud/devportal/discover-apis/ai-agent-discovery.md b/en/docs/cloud/devportal/discover-apis/ai-agent-discovery.md index 401af9f7..90a55cc8 100644 --- a/en/docs/cloud/devportal/discover-apis/ai-agent-discovery.md +++ b/en/docs/cloud/devportal/discover-apis/ai-agent-discovery.md @@ -1,10 +1,10 @@ -# AI Agent API Discovery +# AI agent API discovery API Platform's Developer Portal has built-in support for AI agent discoverability. Every published API is automatically exposed through a set of machine readable endpoints that AI agents, LLM powered assistants, and agentic frameworks can use to discover, understand, and invoke APIs without human assistance. This page explains how those endpoints work and how agents navigate the portal. -## `llms.txt`: The Entry Point for Agents +## `llms.txt`: The entry point for agents The portal dynamically generates an `llms.txt` file — a plain-text Markdown index designed as the entry point for AI agents. It provides a structured overview of everything the portal exposes for AI consumption. @@ -27,18 +27,18 @@ An agent or agentic framework that starts at `llms.txt` immediately understands --- -## Machine Readable API Endpoints +## Machine readable API endpoints Beyond `llms.txt`, the portal exposes all content as clean Markdown and raw specification files. These endpoints require no authentication, no JavaScript rendering, and no browser. Therefore, agents can fetch them reliably as plain text. -### API Catalog and Per API Documentation +### API catalog and per API documentation | Endpoint | Description | |---|---| | `/{orgName}/views/{viewName}/apis.md` | All agent-visible APIs as a single Markdown document | | `/{orgName}/views/{viewName}/api/{apiHandle}.md` | Full documentation for a specific API in Markdown, including description, documents, and a link to the specification | -### API Specifications +### API specifications | Endpoint | Description | |---|---| @@ -46,7 +46,7 @@ Beyond `llms.txt`, the portal exposes all content as clean Markdown and raw spec | `/{orgName}/views/{viewName}/api/{apiHandle}/docs/specification.graphql` | GraphQL schema | | `/{orgName}/views/{viewName}/api/{apiHandle}/docs/specification.xml` | SOAP specification (WSDL/XML) | -### MCP Server Catalog +### MCP server catalog | Endpoint | Description | |---|---| @@ -54,7 +54,7 @@ Beyond `llms.txt`, the portal exposes all content as clean Markdown and raw spec | `/{orgName}/views/{viewName}/mcp/{apiHandle}.md` | Full documentation for a specific MCP server in Markdown | | `/{orgName}/views/{viewName}/mcp/{apiHandle}/docs/specification.json` | MCP server specification | -### API Workflows +### API workflows | Endpoint | Description | |---|---| @@ -62,7 +62,7 @@ Beyond `llms.txt`, the portal exposes all content as clean Markdown and raw spec | `/{orgName}/views/{viewName}/api-workflows/{handle}/arazzo.json` | Machine readable Arazzo specification for a specific workflow | -## How Agents Navigate the Portal +## How agents navigate the portal A typical agent discovery flow looks like this: @@ -73,7 +73,7 @@ A typical agent discovery flow looks like this: 5. **Follow a workflow** — if a published workflow matches the task, the agent retrieves the Arazzo specification and agent prompt to follow a vetted, step-by-step call sequence rather than reasoning from scratch. -## Visibility Controls +## Visibility controls By default, all published APIs and MCP servers are agent-visible. API publishers can hide specific APIs from agent-facing surfaces without affecting their visibility to human users in the portal. Portal admins can also disable AI discoverability across the entire portal. diff --git a/en/docs/cloud/devportal/discover-apis/api-documentations.md b/en/docs/cloud/devportal/discover-apis/api-documentations.md index 9f80b95f..58a08e4a 100644 --- a/en/docs/cloud/devportal/discover-apis/api-documentations.md +++ b/en/docs/cloud/devportal/discover-apis/api-documentations.md @@ -1,8 +1,8 @@ -# API Documentation +# API documentation The API documentation page provides essential information such as endpoints, schemas, security mechanisms, and the base URL. -## View API Documentation +## View API documentation 1. Go to **APIs** in the sidebar. 2. Select an API to view the documentation. diff --git a/en/docs/cloud/devportal/manage-applications/create-an-application.md b/en/docs/cloud/devportal/manage-applications/create-an-application.md index 6ac5a629..652ad7b7 100644 --- a/en/docs/cloud/devportal/manage-applications/create-an-application.md +++ b/en/docs/cloud/devportal/manage-applications/create-an-application.md @@ -1,4 +1,4 @@ -# Create Applications +# Create applications An application is a logical representation of a physical application such as a mobile app, webapp, device, etc. If an application needs to consume an API, it should subscribe to the required API over a selected business plan, which determines the usage quota the application is allowed. A single application can have multiple API subscriptions. @@ -34,7 +34,7 @@ This creates the organization and opens the **Project Home** page of the default ![Applications list showing DemoBookingApp, Testapp01, and SampleIntegrationApp cards with subscription counts](../../../assets/img/devportal/applications-list.png) -## Add Application Description +## Add application description 1. Selected application. 2. Click **+ Add description** to add the application's description. diff --git a/en/docs/cloud/devportal/sdk-generation/ai-assisted-sdk-generation.md b/en/docs/cloud/devportal/sdk-generation/ai-assisted-sdk-generation.md index 78ad395d..2494d289 100644 --- a/en/docs/cloud/devportal/sdk-generation/ai-assisted-sdk-generation.md +++ b/en/docs/cloud/devportal/sdk-generation/ai-assisted-sdk-generation.md @@ -1,8 +1,8 @@ -# AI-Assisted SDK Generation +# AI-assisted SDK generation AI-assisted SDK generation creates custom SDKs and sample application code based on your selected APIs. Instead of manually integrating multiple SDKs, you generate a single SDK with working code examples tailored to your specific requirements. -## What is AI-assisted SDK Generation? +## What is AI-assisted SDK generation? Building applications with multiple APIs typically requires you to: @@ -29,7 +29,7 @@ Before proceeding, ensure you have [Created an Application](../manage-applicatio Follow these steps to generate a custom SDK and sample application code. -### Step 1: Select APIs for SDK Generation +### Step 1: Select APIs for SDK generation 1. Navigate to the [API Platform Developer Portal](https://devportal.bijira.dev) and sign in. 2. Click on **Applications** in the Developer Portal sidebar. @@ -58,7 +58,7 @@ Follow these steps to generate a custom SDK and sample application code. ![Generate SDK panel showing Generating SDK progress bar at 40 percent with in-progress status message](../../../assets/img/devportal/sdk_generation_in_progress.png) -## Important Notes +## Important notes - AI services require valid configuration and active subscriptions. - Generated code serves as a starting point and may need customization. diff --git a/en/docs/cloud/devportal/theming-devportal-api-level.md b/en/docs/cloud/devportal/theming-devportal-api-level.md index 5bd0defe..9008010f 100644 --- a/en/docs/cloud/devportal/theming-devportal-api-level.md +++ b/en/docs/cloud/devportal/theming-devportal-api-level.md @@ -1,4 +1,4 @@ -# Customize Developer Portal Manually for your Organization +# Customize Developer Portal manually for your organization Developer portal allows you to customize the user interfaces (UIs) in organization level as well as in API level. With this you can ensure that your pages not only look great but also align perfectly with your brand's identity. @@ -25,7 +25,7 @@ Go through the below steps to get the `Developer Portal` tab. - In the left navigation menu, click `Admin` and then click `Settings`. - Select `Developer Portal` tab. -## Theme your Devportal in API Level +## Theme your Devportal in API level Go through the following steps to customize the theme of the Devportal in the API level. @@ -68,7 +68,7 @@ Here you can adjust appearance of the API Overview page by changing the css styl 2. Click **Publish to Developer Portal** to publish the CSS changes. -### Customize API Landing Page content +### Customize API landing page content To customize the content of an API go through the following steps. diff --git a/en/docs/cloud/devportal/theming-devportal-org-level.md b/en/docs/cloud/devportal/theming-devportal-org-level.md index a2a1b20d..609dc9ea 100644 --- a/en/docs/cloud/devportal/theming-devportal-org-level.md +++ b/en/docs/cloud/devportal/theming-devportal-org-level.md @@ -1,4 +1,4 @@ -# Customize Developer Portal Manually for your Organization +# Customize Developer Portal manually for your organization Developer portal allows you to customize the user interfaces (UIs) in organization level as well as in API level. With this you can ensure that your pages not only look great but also align perfectly with your brand's identity. @@ -25,11 +25,11 @@ Go through the below steps to get the `Developer Portal` tab. - In the left navigation menu, click `Admin` and then click `Settings`. - Select `Developer Portal` tab. -## Theme your Devportal in Org Level +## Theme your Devportal in org level Go through the following steps to customize the theme of the Devportal in the organization level. -### Theme Settings +### Theme settings 1. Select `Org Level` tab. 2. Select `Theme Settings` tab. Here, you can manage and customize theme colors for your organization. diff --git a/en/docs/cloud/devportal/theming-devportal-with-ai.md b/en/docs/cloud/devportal/theming-devportal-with-ai.md index 19cc5139..007d2e80 100644 --- a/en/docs/cloud/devportal/theming-devportal-with-ai.md +++ b/en/docs/cloud/devportal/theming-devportal-with-ai.md @@ -1,6 +1,6 @@ -# Theming Developer Portal with AI for your Organization +# Theming Developer Portal with AI for your organization -AI-powered branding simplifies the process of customizing your organization's Developer portal. By leveraging AI Branding, you can ensure that your pages not only look great but also align perfectly with your brand's identity. +AI-powered branding simplifies the process of customizing your organization's Developer portal. By leveraging AI branding, you can ensure that your pages not only look great but also align perfectly with your brand's identity. ## Prerequisites diff --git a/en/docs/cloud/event-gateway/getting-started.md b/en/docs/cloud/event-gateway/getting-started.md index d6bf8c54..10ec6aed 100644 --- a/en/docs/cloud/event-gateway/getting-started.md +++ b/en/docs/cloud/event-gateway/getting-started.md @@ -1,4 +1,4 @@ -# Getting Started with Event Gateway +# Getting started with Event Gateway This guide walks you through setting up an API Platform Event Gateway in your environment. Follow these quick steps to get your gateway running and connected to API Platform's control plane. @@ -19,7 +19,7 @@ Before you begin, ensure you have: - **Docker** installed and running (for Quick Start) - **Docker Compose** installed -## Create an Event Gateway in API Platform Console +## Create an Event Gateway in API Platform console 1. Sign in to [API Platform Console](https://console.bijira.dev). 2. Go to **Organization Level** in API Platform. @@ -37,14 +37,14 @@ Before you begin, ensure you have: 8. Click **Add** and you will be navigated to the Gateway View Page. -## Setup Gateway +## Setup gateway 1. Next, download, set up, and start the gateway on your machine by following the steps in the **Quick Start** section or the detailed instructions below (Steps 1–4). !!! note Be sure to copy the commands from the Quick Start section, since the keys are auto-generated for you. -### Step 1: Download the Gateway +### Step 1: Download the gateway Run this command in your terminal to download the gateway: @@ -53,7 +53,7 @@ curl -sLO https://github.com/wso2/api-platform/releases/download/event-gateway/v unzip wso2apip-event-gateway-0.8.0.zip ``` -### Step 2: Configure the Gateway +### Step 2: Configure the gateway Run this command to create the gateway configuration with your environment variables: @@ -66,7 +66,7 @@ ENVFILE Once you copy the above command from the screen, the `` placeholder will be populated and the `wso2apip-event-gateway-0.8.0/configs/keys.env` file will be created with these environment variables. -### Step 3: Start the Gateway +### Step 3: Start the gateway Navigate to the gateway directory and start it using Docker Compose: @@ -75,7 +75,7 @@ cd wso2apip-event-gateway-0.8.0 docker compose --env-file configs/keys.env up ``` -### Step 4: Verify the Gateway +### Step 4: Verify the gateway Check that the gateway is running and connected: @@ -89,12 +89,12 @@ curl http://localhost:9002/health The gateway should show as **Active** in the API Platform Console under **Gateways**. -## Add API and Invoke +## Add API and invoke !!! note This feature is currently available only for **WEBSUB** API proxies. -### Step 1: Create an API Proxy. +### Step 1: Create an API proxy. In this guide, you will create a WEBSUB API proxy to route through the Event Gateway. @@ -110,7 +110,7 @@ In this guide, you will create a WEBSUB API proxy to route through the Event Gat 6. Click **Create** to create the API Proxy. Wait for the setup to complete and you will be navigated to the API Overview Page. -### Step 2: Deploy the API Proxy (Optional) +### Step 2: Deploy the API proxy (optional) !!! note This step is **optional** at this stage, as the API is deployed to the gateway by default. However, if you make any changes to the API, you must redeploy it. @@ -121,17 +121,17 @@ In this guide, you will create a WEBSUB API proxy to route through the Event Gat 2. Click **Deploy**. -## Test the API Proxy +## Test the API proxy 1. Navigate to the **Test** page of the API Proxy. 2. Use the available test client for the relevant resource to test the API Proxy. -## Next Steps +## Next steps Your Event Gateway is now running! Here's what to do next: -## Alternative Deployment Options +## Alternative deployment options For production environments or specific infrastructure requirements, see the detailed configuration guide: diff --git a/en/docs/cloud/event-gateway/overview.md b/en/docs/cloud/event-gateway/overview.md index 8088b858..509bd0f6 100644 --- a/en/docs/cloud/event-gateway/overview.md +++ b/en/docs/cloud/event-gateway/overview.md @@ -1,21 +1,21 @@ -# Event Gateway Overview +# Event Gateway overview The Event Gateway is a self-hosted runtime that performs **Protocol Mediation** — acting as the bridge between web-friendly protocols (WebSocket, WebHook, SSE) and message brokers (Kafka, MQTT, Solace). It enables you to expose event brokers as subscribable APIs while enforcing policies such as authentication, authorization, and rate limiting through the centralized API Platform’s Policy Hub. -## Quick Start +## Quick start - [Getting Started](getting-started.md) - Create an event gateway in the API Platform Console, download and start the gateway, and deploy a WEBSUB API proxy -## What is Protocol Mediation? +## What is protocol mediation? Traditional API gateways are designed for request-response traffic. Event-driven architectures, however, use message brokers such as Kafka and MQTT, which communicate over broker-specific protocols that are not directly accessible to web clients. Protocol Mediation solves this by placing the Event Gateway between the broker and web clients, translating between broker protocols and web-friendly protocols such as WebSocket, WebHook, and Server-Sent Events (SSE). This means external clients can consume from or produce messages to an event broker using standard web protocols, without needing native broker client support. -## Key Concepts +## Key concepts -### Event Gateway Architecture +### Event Gateway architecture The Event Gateway consists of three components that work together in the mediation flow: diff --git a/en/docs/cloud/event-gateway/publish-apis/lifecycle-management.md b/en/docs/cloud/event-gateway/publish-apis/lifecycle-management.md index d52d3d05..d173f260 100644 --- a/en/docs/cloud/event-gateway/publish-apis/lifecycle-management.md +++ b/en/docs/cloud/event-gateway/publish-apis/lifecycle-management.md @@ -1,10 +1,10 @@ -# Lifecycle Management +# Lifecycle management API lifecycle management is an important aspect of API management. The API lifecycle consists of various states that an API passes through, from creation to retirement. In API Platform, there are five distinct lifecycle states: created, pre-released, published, deprecated, and retired. By leveraging the various lifecycle states, API managers can optimize the development process and ensure that subscribers have access to the latest and most reliable APIs. -## API Lifecycle States +## API lifecycle states The following lifecycle states are applicable to APIs in API Platform: @@ -16,7 +16,7 @@ The following lifecycle states are applicable to APIs in API Platform: | **DEPRECATED** | The old version of an API is moved to this state when a newer version of the API is PUBLISHED.| The API is deployed and is available to existing subscribers. New subscriptions are disabled. Existing subscribers can continue to use it as usual until the API is retired.| | **RETIRED** | The API is no longer in use when it is in this state.| The API is unpublished and deleted from the Developer Portal.| -## Manage the Lifecycle of an API +## Manage the lifecycle of an API To change the lifecycle state of an API via the API Platform Console, follow the instructions given below: diff --git a/en/docs/cloud/event-gateway/publish-apis/subscription-based-apis.md b/en/docs/cloud/event-gateway/publish-apis/subscription-based-apis.md index 84740320..32e1b24e 100644 --- a/en/docs/cloud/event-gateway/publish-apis/subscription-based-apis.md +++ b/en/docs/cloud/event-gateway/publish-apis/subscription-based-apis.md @@ -18,7 +18,7 @@ This model fits APIs where you need tiered access, usage limits, or clear commer For detailed steps and field behavior, see [Assign Subscription Plans to APIs](../../develop-api-proxy/subscription-plans.md). -## Assign Subscription Validation Policy to the API +## Assign subscription validation policy to the API 1. Go to **Develop** → **Policies**. diff --git a/en/docs/cloud/event-gateway/setting-up.md b/en/docs/cloud/event-gateway/setting-up.md index 09a83283..58b50adc 100644 --- a/en/docs/cloud/event-gateway/setting-up.md +++ b/en/docs/cloud/event-gateway/setting-up.md @@ -1,11 +1,11 @@ -# Setting Up +# Setting up This guide provides detailed instructions for deploying the API Platform Event Gateway in production environments. Choose the infrastructure option that matches your environment. !!! tip "Quick Start" If you're just getting started, see the [Getting Started](getting-started.md) guide for a quick setup. -## Setup Instructions +## Setup instructions === "Virtual Machine" @@ -215,6 +215,6 @@ This guide provides detailed instructions for deploying the API Platform Event G helm uninstall event-gateway ``` -## What's Next? +## What's next? - [Troubleshooting](troubleshooting.md): Common issues and solutions diff --git a/en/docs/cloud/event-gateway/troubleshooting.md b/en/docs/cloud/event-gateway/troubleshooting.md index 034e7057..cbac766c 100644 --- a/en/docs/cloud/event-gateway/troubleshooting.md +++ b/en/docs/cloud/event-gateway/troubleshooting.md @@ -2,9 +2,9 @@ This guide covers common issues you may encounter when deploying and operating the API Platform Event Gateway, along with their solutions. -## Connection Issues +## Connection issues -### Gateway Not Connecting to Control Plane +### Gateway not connecting to control plane **Symptoms:** @@ -46,7 +46,7 @@ This guide covers common issues you may encounter when deploying and operating t noProxy: "localhost,127.0.0.1,.internal.example.com" ``` -### Intermittent Disconnections +### Intermittent disconnections **Symptoms:** @@ -77,9 +77,9 @@ This guide covers common issues you may encounter when deploying and operating t Ensure load balancers or firewalls don't have aggressive idle timeouts. -## Registration Issues +## Registration issues -### Invalid Gateway Token +### Invalid gateway token **Symptoms:** @@ -113,7 +113,7 @@ This guide covers common issues you may encounter when deploying and operating t cat configs/keys.env | grep GATEWAY_REGISTRATION_TOKEN ``` -### Token Revoked +### Token revoked **Symptoms:** @@ -126,9 +126,9 @@ This guide covers common issues you may encounter when deploying and operating t 2. Update the gateway configuration. 3. Restart the gateway. -## Startup Issues +## Startup issues -### Gateway Pod/Container Not Starting +### Gateway pod/container not starting **Symptoms:** @@ -175,7 +175,7 @@ This guide covers common issues you may encounter when deploying and operating t bijira-event-gateway --config /etc/bijira/gateway.yaml --validate ``` -### Port Already in Use +### Port already in use **Symptoms:** @@ -199,9 +199,9 @@ This guide covers common issues you may encounter when deploying and operating t port: 8443 # Use alternative port ``` -## TLS/Certificate Issues +## TLS/Certificate issues -### Certificate Not Valid +### Certificate not valid **Symptoms:** @@ -232,7 +232,7 @@ This guide covers common issues you may encounter when deploying and operating t openssl rsa -noout -modulus -in private.key | openssl md5 ``` -### Certificate Expired +### Certificate expired **Symptoms:** @@ -256,9 +256,9 @@ This guide covers common issues you may encounter when deploying and operating t sudo systemctl reload bijira-event-gateway ``` -## Policy Issues +## Policy issues -### Policies Not Applied +### Policies not applied **Symptoms:** @@ -284,7 +284,7 @@ This guide covers common issues you may encounter when deploying and operating t grep -i "policy" /var/log/bijira/event-gateway.log ``` -### Policy Conflicts +### Policy conflicts **Symptoms:** @@ -301,9 +301,9 @@ This guide covers common issues you may encounter when deploying and operating t 3. Use the policy simulation tool in API Platform Console. -## Performance Issues +## Performance issues -### High Latency +### High latency **Symptoms:** @@ -345,7 +345,7 @@ This guide covers common issues you may encounter when deploying and operating t Ensure the gateway has low-latency access to backend services. -### High Memory Usage +### High memory usage **Symptoms:** @@ -379,9 +379,9 @@ This guide covers common issues you may encounter when deploying and operating t ttl: 300s ``` -## API Routing Issues +## API routing issues -### 404 Not Found Errors +### 404 not found errors **Symptoms:** @@ -402,7 +402,7 @@ This guide covers common issues you may encounter when deploying and operating t 3. **Verify the request path matches the API configuration.** -### 502 Bad Gateway Errors +### 502 bad gateway errors **Symptoms:** @@ -432,9 +432,9 @@ This guide covers common issues you may encounter when deploying and operating t readTimeout: 60s ``` -## Logging and Diagnostics +## Logging and diagnostics -### Enable Debug Logging +### Enable debug logging Temporarily enable debug logging for troubleshooting: @@ -446,7 +446,7 @@ logging: !!! warning Debug logging can generate large volumes of logs and impact performance. Disable after troubleshooting. -### Collect Diagnostic Information +### Collect diagnostic information When opening a support request, collect: @@ -479,7 +479,7 @@ When opening a support request, collect: df -h ``` -## Getting Help +## Getting help If you cannot resolve an issue using this guide: @@ -487,7 +487,7 @@ If you cannot resolve an issue using this guide: 2. **Search known issues:** Check the API Platform status page and release notes. 3. **Contact support:** Open a support ticket with diagnostic information. -## What's Next? +## What's next? - [Getting Started](getting-started.md): Quick start guide - [Setting Up](setting-up.md): Configuration guide diff --git a/en/docs/cloud/federation/api-discovery-aws.md b/en/docs/cloud/federation/api-discovery-aws.md index b5c93b0f..682e4bb7 100644 --- a/en/docs/cloud/federation/api-discovery-aws.md +++ b/en/docs/cloud/federation/api-discovery-aws.md @@ -14,7 +14,7 @@ Before you begin, ensure you have: --- -## Step 1: Configure User Credentials in AWS API Gateway +## Step 1: Configure user credentials in AWS API Gateway 1. Login to your AWS account and navigate to Console Home. Search for "IAM" in the search bar. 2. Click on the IAM service. Navigate to Users under Access Management. @@ -26,21 +26,21 @@ Before you begin, ensure you have: --- -## Step 2: Add an External Gateway in API Platform +## Step 2: Add an external gateway in API Platform Now that you have your AWS credentials ready, configure the external gateway connection in API Platform. -1. Navigate to **Organization Level** in API Platform. +1. Navigate to **Organization level** in API Platform. 2. Click **Add External Gateway**. ![External Gateway empty state page with Add Gateway button and API gateway icon, shown under Admin > External Gateway menu](../../assets/img/gateway-federation/add-external-gateway.png) 3. Enter the gateway configuration details: - - **Gateway Name:** A descriptive name for this gateway (e.g., `Production AWS API Gateway`) + - **Gateway name:** A descriptive name for this gateway (e.g., `Production AWS API Gateway`) - **Region:** The AWS region where your API Gateway is deployed (e.g., `us-east-1`) - **Stage:** The API Gateway stage to discover APIs from (e.g., `prod`, `dev`) - - **Access Key :** The Access Key from Step 1 - - **Secret Key:** The Secret Key from Step 1 + - **Access key:** The Access Key from Step 1 + - **Secret key:** The Secret Key from Step 1 4. Click **Save** ![Add External Gateway form with AWS vendor selected, display name, description, AWS region us-east-1, stage name dev, access key, and secret key fields](../../assets/img/gateway-federation/add-external-gateway-form.png){ width="800" } @@ -49,7 +49,7 @@ The external gateway is now connected to API Platform and ready for API discover --- -## Step 3: Discover APIs from the Gateway +## Step 3: Discover APIs from the gateway Once the external gateway is configured, you can discover and federate APIs into API Platform. diff --git a/en/docs/cloud/federation/overview.md b/en/docs/cloud/federation/overview.md index 660e933e..22477db2 100644 --- a/en/docs/cloud/federation/overview.md +++ b/en/docs/cloud/federation/overview.md @@ -1,21 +1,21 @@ -# Gateway Federation in API Platform +# Gateway federation in API Platform -## What is Gateway Federation? +## What is gateway federation? -## Gateway Federation Overview +## Gateway federation overview Gateway federation in API Platform empowers organizations to seamlessly manage, govern, and expose APIs deployed on external gateways, all from a single, unified control plane. Instead of manually tracking APIs across different platforms, API Platform enables you to: -- **Discover External APIs:** Automatically find APIs hosted on external gateways and bring them under API Platform’s management. -- **Centralize Governance:** Apply consistent API governance compliance policies to all federated APIs, regardless of where they are deployed. -- **Monitor & Enforce Compliance:** Continuously monitor API activity and ensure adherence to organizational governance policies. -- **Enable Developer Access:** Make APIs easily discoverable and consumable for developers through the API Platform Developer Portal, streamlining onboarding and integration. +- **Discover external APIs:** Automatically find APIs hosted on external gateways and bring them under API Platform’s management. +- **Centralize governance:** Apply consistent API governance compliance policies to all federated APIs, regardless of where they are deployed. +- **Monitor and enforce compliance:** Continuously monitor API activity and ensure adherence to organizational governance policies. +- **Enable developer access:** Make APIs easily discoverable and consumable for developers through the API Platform Developer Portal, streamlining onboarding and integration. By federating gateways with API Platform, you gain complete visibility and control over your API landscape, reduce operational complexity, and accelerate secure API delivery to consumers and partners. -## Getting Started +## Getting started -1. **Register External Gateway:** Add the external gateway configuration in API Platform. +1. **Register external gateway:** Add the external gateway configuration in API Platform. 2. **Discover APIs:** Discover APIs from the external gateway and create them in the API Platform control plane. -3. **Apply Governance:** Define governance policies and monitor governance compliance for the discovered APIs. -4. **Expose to Developers:** Make APIs available for consumption by publishing to the API Platform Developer Portal. +3. **Apply governance:** Define governance policies and monitor governance compliance for the discovered APIs. +4. **Expose to developers:** Make APIs available for consumption by publishing to the API Platform Developer Portal. diff --git a/en/docs/cloud/governance/govern-api-proxy.md b/en/docs/cloud/governance/govern-api-proxy.md index 153434b1..b40ba372 100644 --- a/en/docs/cloud/governance/govern-api-proxy.md +++ b/en/docs/cloud/governance/govern-api-proxy.md @@ -11,7 +11,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Govern API Proxies +# Govern API proxies API governance lets you enforce compliance standards on API proxies across your organization. You can define rulesets, attach them to policies, and monitor adherence through a compliance dashboard. You can also upload governance documents to run AI-powered compliance analysis against your APIs. @@ -24,7 +24,7 @@ The Governance page is organized into two main sections, toggled at the top: Rulesets are Spectral YAML-based rule definitions used to validate API artifacts. They are listed under the **Policies** tab in the **Rulesets** section. Once created, rulesets are attached to policies to enforce them on your API proxies. -### Create a Ruleset +### Create a ruleset 1. Sign in to the [API Platform Console](https://console.bijira.dev/). 2. In the API Platform Console header, go to the **Organization** list and select your organization. @@ -54,7 +54,7 @@ Rulesets are Spectral YAML-based rule definitions used to validate API artifacts Policies attach one or more rulesets to your organization's API proxies and define when and how they are enforced. You can use the default rulesets available in the catalog or create your own. Once created, a policy is automatically applied globally to all existing and newly created API proxies in the organization. -### Create a Policy +### Create a policy 1. On the Governance page, ensure the **Policies** tab is selected. 2. Click **Add Policy**. @@ -72,7 +72,7 @@ Policies attach one or more rulesets to your organization's API proxies and defi ![Create Policy form showing name, description, Global applicability, Enforcement Details table with Update state and Notify buttons for On Error, On Warning, and On Info, plus selectable ruleset cards including Sample Ruleset, WSO2 API Design Guidelines, WSO2 Style Guidelines, and OWASP Top 10](../../assets/img/governance/add-policy.png) -### Enforcement Detail +### Enforcement detail | Field Name | Description | Mandatory | Options/Values | |---|---|---|---| @@ -86,7 +86,7 @@ Policies attach one or more rulesets to your organization's API proxies and defi Documents are PDF files containing governance standards written in natural language. They are used as guidelines by the AI Compliance Analysis feature when evaluating your APIs. -### Add a Document +### Add a document 1. On the Governance page, select the **Documents** tab. 2. Click **Add Document** and provide the following details: @@ -101,6 +101,6 @@ Documents are PDF files containing governance standards written in natural langu ![Create Document form with name field showing Sample Document, selected PDF file for Best Practices Guidelines for REST API Design in the Banking Sector, and description field with Cancel and Create buttons](../../assets/img/governance/add-document.png) -## Monitoring Compliance +## Monitoring compliance Once policies are applied, compliance results are available through the Compliance Dashboard under **Insights > Compliance** at the organization, project, and component levels. For details on viewing compliance results and running AI compliance analysis, see [Compliance Dashboard](../monitoring-and-insights/compliance.md). diff --git a/en/docs/cloud/governance/overview.md b/en/docs/cloud/governance/overview.md index b9b67e43..9218b416 100644 --- a/en/docs/cloud/governance/overview.md +++ b/en/docs/cloud/governance/overview.md @@ -11,25 +11,25 @@ last_updated: 2026-06-18 content_type: "concept" --- -# API Platform API Management Governance +# API Platform API management governance API Management Governance consists of a set of processes, practices, roles, and responsibilities designed to ensure the effective and efficient management of APIs throughout their lifecycle. Establishing a governance strategy is essential for maintaining consistency, security, and compliance in API development, management, and consumption. Implementing API governance provides the following benefits: -- **Security and Compliance** – Enforces authentication, authorization, and regulatory compliance requirements. +- **Security and compliance** – Enforces authentication, authorization, and regulatory compliance requirements. - **Consistency** – Standardizes API design, documentation, and versioning to maintain uniformity. -- **Performance and Reliability** – Enables monitoring, rate limiting, and policy enforcement to ensure optimal API performance. -- **Lifecycle Management** – Supports structured API development, deployment, deprecation, and retirement processes. +- **Performance and reliability** – Enables monitoring, rate limiting, and policy enforcement to ensure optimal API performance. +- **Lifecycle management** – Supports structured API development, deployment, deprecation, and retirement processes. - **Collaboration** – Defines clear roles and responsibilities for API stakeholders, improving coordination. -- **Discoverability and Reusability** – Facilitates API cataloging and reuse to minimize redundant development efforts. -- **Business Agility** – Accelerates API delivery, helping organizations meet customer and partner needs efficiently. +- **Discoverability and reusability** – Facilitates API cataloging and reuse to minimize redundant development efforts. +- **Business agility** – Accelerates API delivery, helping organizations meet customer and partner needs efficiently. API Platform API Management provides a comprehensive governance capabilities that powered by AI to evaluate API compliance with governance standards given in a form of natural language specification, and also spectral based compliance validation for rules defined in OpenAPI and AsyncAPI specifications. This section outlines the governance concepts available in API Platform. -## Governance Concepts +## Governance concepts API Management Governance build on the following concepts @@ -39,9 +39,9 @@ A ruleset is a collection of rules that define governance policies to be enforce Each ruleset must have a unique name and may include a description to provide additional context. Rulesets are used to validate specific aspects of an API, including: -- **API Definition** – The OpenAPI or AsyncAPI definition that establishes the API contract. -- **API Metadata** – Information about the API, such as name, version, context, and other details. -- **API Documentation** – Documentation that provides usage guidelines and other relevant information about the API. +- **API definition** – The OpenAPI or AsyncAPI definition that establishes the API contract. +- **API metadata** – Information about the API, such as name, version, context, and other details. +- **API documentation** – Documentation that provides usage guidelines and other relevant information about the API. When defining a ruleset, the API type must be specified. Supported API types include: @@ -58,19 +58,19 @@ A **policy** is a set of rulesets that define governance policies to be enforced Each policy must have a **unique name** and may include a **description** to provide additional context. -#### Policy Attachment and Labeling +#### Policy attachment and labeling Policies can be attached to one or more **labels** to categorize them effectively. Labels serve as a link between policies and APIs when a policy is assigned to a label, it is automatically applied to all APIs associated with that label. -#### Policy Enforcement +#### Policy enforcement Policy enforcement is an integral part of policy definition and can be categorized into three types: -#### 1. Policy Enforcement on APIs +#### 1. Policy enforcement on APIs All the policies will be enforced on the API proxies when the proxies are updated. -#### 2. Rule Violation Level +#### 2. Rule violation level Policies can be enforced based on the severity of rule violations. The supported levels include: @@ -78,7 +78,7 @@ Policies can be enforced based on the severity of rule violations. The supported - **Warn** – Indicates a warning that requires attention. - **Info** – Provides informational messages about compliance. -#### 3. Rule Violation Action +#### 3. Rule violation action Policies define actions to be taken when a rule violation is detected. The supported actions include: diff --git a/en/docs/cloud/introduction/quick-start-guide-mcp.md b/en/docs/cloud/introduction/quick-start-guide-mcp.md index 57e8f399..1f839c18 100644 --- a/en/docs/cloud/introduction/quick-start-guide-mcp.md +++ b/en/docs/cloud/introduction/quick-start-guide-mcp.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "quickstart" --- -# Quick Start Guide - MCP Server +# Quick start guide - MCP server API Platform provides a complete solution for transforming existing APIs into intelligent, AI-ready tools using the Model Context Protocol (MCP). With a centralized control plane, API Platform simplifies the entire lifecycle of MCP server management from creation to discovery delivering a seamless experience for both API developers and AI agent builders. @@ -28,7 +28,7 @@ In this tutorial, you will use API Platform to create an MCP Server from an HTTP This creates the organization and opens the organization home page. -## Step 1: Create a Project +## Step 1: Create a project 1. Go to [API Platform Console](https://console.bijira.dev/) and sign in. This opens the organization home page. 2. On the organization home page, click **+ Create Project**. @@ -45,7 +45,7 @@ In this tutorial, you will use API Platform to create an MCP Server from an HTTP 4. Click **Create**. This creates the project and takes you to the project home page. -## Step 2: Create an MCP Server +## Step 2: Create an MCP server 1. On the project home page, select **MCP Server** and click **Import API Contract** under **Expose APIs as MCP Servers**. 2. Click **URL for API Contract**, enter the following URL, and then click **Next**: @@ -56,7 +56,7 @@ In this tutorial, you will use API Platform to create an MCP Server from an HTTP ![Create MCP Server from Contract form with name Reading List API, identifier, version, base path, description, HTTP type, WSO2 Managed Gateway selected, and target URL fields](../../assets/img/introduction/mcp-create-server.png) -## Step 3: Test the MCP Server +## Step 3: Test the MCP server API Platform automatically generates tool schemas based on the information available in your API contract. @@ -76,7 +76,7 @@ In this guide, you will use the MCP Playground. ![MCP Playground in Development environment showing Connected status, five tools listed including listBooks selected, and successful JSON tool result with book records](../../assets/img/introduction/mcp-inspector.png) -## Step 4: Promote and Publish the MCP Server +## Step 4: Promote and publish the MCP server Once you verify the MCP Server is working as expected in development, promote it to production and publish it for consumers. @@ -93,18 +93,18 @@ Once you verify the MCP Server is working as expected in development, promote it Now that your MCP Server is deployed in both development and production environments and can be invoked, the next step is to publish it so that consumers can discover and subscribe to it. -## Step 5: Publish the MCP Server +## Step 5: Publish the MCP server 1. In the left navigation menu, click **Develop** and then click **Lifecycle**. This opens the **Lifecycle** page, where you can see the different lifecycle stages of the MCP Server. The current lifecycle stage is **Created**. 2. Click **Publish**. 3. In the **Publish MCP Server** dialog, click **Confirm** to publish the MCP Server with the specified display name. If you want to change the display name, make the necessary changes and then click **Confirm**. This changes the lifecycle state to **Published**. - !!! Info + !!! info If you want to configure the Developer Portal as an MCP Hub, follow the [Developer Portal Mode](../devportal/developer-portal-mode.md) documentation. The MCP Server is now available for consumers to discover and subscribe to via the API Platform Developer Portal. -## Step 6: Connect with an MCP Client +## Step 6: Connect with an MCP client MCP Servers in API Platform are secured by OAuth2 by default. To access an MCP Server, you must subscribe through an application, obtain a valid token, and configure it in your MCP client. diff --git a/en/docs/cloud/introduction/quick-start-guide.md b/en/docs/cloud/introduction/quick-start-guide.md index 4e7f46b6..1b733bf3 100644 --- a/en/docs/cloud/introduction/quick-start-guide.md +++ b/en/docs/cloud/introduction/quick-start-guide.md @@ -1,5 +1,5 @@ --- -title: "Quick Start Guide - API Proxy" +title: "Quick start guide - API proxy" description: "Expose a service as an API proxy with WSO2 API Platform and publish it to the Developer Portal for application developers to consume." canonical_url: https://wso2.com/api-platform/docs/cloud/introduction/quick-start-guide/ md_url: https://wso2.com/api-platform/docs/cloud/introduction/quick-start-guide.md @@ -12,7 +12,7 @@ last_updated: 2026-06-11 content_type: "quickstart" --- -# Quick Start Guide - API Proxy +# Quick start guide - API proxy WSO2 API Platform simplifies securely exposing existing services as managed APIs. It also allows you to manage all aspects of an API's lifecycle, security, throttling, and governance, so you can focus on service development. @@ -28,7 +28,7 @@ In this tutorial, you will use API Platform to expose a service as an API proxy This creates the organization and opens the organization home page. -## Step 1: Create a Project +## Step 1: Create a project 1. Go to [API Platform Console](https://console.bijira.dev/) and sign in. This opens the organization home page. 2. On the organization home page, click **+ Create Project**. @@ -45,7 +45,7 @@ In this tutorial, you will use API Platform to expose a service as an API proxy 4. Click **Create**. This creates the project and takes you to the project home page. -## Step 2: Create an API Proxy +## Step 2: Create an API proxy 1. On the project home page, click **Import API Contract** under **My APIs (Ingress)**. 2. Click **URL for API Contract**, enter the following URL, and then click **Next**: @@ -55,7 +55,7 @@ In this tutorial, you will use API Platform to expose a service as an API proxy 3. **Create API Proxy from Contract** page will be opened. Click **Create** to complete the API proxy creation process. ![Create API Proxy from Contract form with HTTP type, name Sample API, identifier, version, base path, description, target URL, and External and Internal access mode options](../../assets/img/introduction/create-api-proxy-from-contract.png) -## Step 3: Test the API Proxy +## Step 3: Test the API proxy You can test the API proxy in the development environment before promoting it to production. API Platform provides the following options to test your API proxy: @@ -78,7 +78,7 @@ In this guide, you will use the OpenAPI Console. This indicates that your API proxy is working as expected. -## Step 4: Promote the API Proxy to Production +## Step 4: Promote the API proxy to production Once you verify that the API proxy is working as expected in the development environment, you can promote it to production. @@ -95,7 +95,7 @@ Once you verify that the API proxy is working as expected in the development env Now that your API is deployed in both development and production environments and can be invoked, the next step is to publish it so that consumers can discover and subscribe to it. -## Step 5: Publish the API Proxy +## Step 5: Publish the API proxy 1. In the left navigation menu, click **Develop** and then click **Lifecycle**. This opens the **Lifecycle** page, where you can see the different lifecycle stages of the API. The current lifecycle stage is **Created**. 2. Click **Publish**. diff --git a/en/docs/cloud/introduction/what-is-bijira.md b/en/docs/cloud/introduction/what-is-bijira.md index 27789d7f..ff072d1b 100644 --- a/en/docs/cloud/introduction/what-is-bijira.md +++ b/en/docs/cloud/introduction/what-is-bijira.md @@ -18,30 +18,30 @@ API Platform Cloud is next-generation, AI-native SaaS solution for full lifecycl Powered by the proven foundation of WSO2 API Manager and enriched with key innovations from Choreo, API Platform Cloud delivers a seamless developer experience, intelligent governance, and enterprise-grade scalability. -## Key Capabilities of API Platform Cloud +## Key capabilities of API Platform Cloud -### API Design and Development -- **Seamless API Creation:** Design, document, and publish APIs effortlessly using a visual interface or natural-language prompts powered by GenAI. -- **Contract-First and No-Code Options:** Import OpenAPI/AsyncAPI specs or use low-code tools to define API behavior. +### API design and development +- **Seamless API creation:** Design, document, and publish APIs effortlessly using a visual interface or natural-language prompts powered by GenAI. +- **Contract-first and no-code options:** Import OpenAPI/AsyncAPI specs or use low-code tools to define API behavior. -### API Security and Governance +### API security and governance -- **Robust Access Control:** Enforce fine-grained authentication and authorization with OAuth2, OIDC, and role-based access control. -- **Governance-as-Code:** Apply API design and security best practices using AI-assisted policy validation and rulesets. -- **Rate Limiting and Throttling:** Protect APIs from abuse with granular control over traffic and quotas. +- **Robust access control:** Enforce fine-grained authentication and authorization with OAuth2, OIDC, and role-based access control. +- **Governance-as-code:** Apply API design and security best practices using AI-assisted policy validation and rulesets. +- **Rate limiting and throttling:** Protect APIs from abuse with granular control over traffic and quotas. -### API Lifecycle Management +### API lifecycle management -- **Comprehensive Lifecycle Support:** From design to deprecation, API Platform Cloud streamlines API versioning, deployment, testing, promotion, and retirement. +- **Comprehensive lifecycle support:** From design to deprecation, API Platform Cloud streamlines API versioning, deployment, testing, promotion, and retirement. -### Developer Experience and API Discoverability +### Developer experience and API discoverability - **Developer Portal:** Offer a branded, self-service portal for API discovery, subscription, and interactive testing. -- **Auto-Generated Documentation:** Improve usability and adoption with dynamic, always up-to-date API docs. +- **Auto-generated documentation:** Improve usability and adoption with dynamic, always up-to-date API docs. -### Analytics and Monitoring +### Analytics and monitoring -- **Real-time Insights:** Monitor API performance, consumer behavior, latency, and error rates through built-in analytics dashboards. -- **Detailed Logging and Tracing:** Enable full observability with structured logs, metrics, and event tracking. +- **Real-time insights:** Monitor API performance, consumer behavior, latency, and error rates through built-in analytics dashboards. +- **Detailed logging and tracing:** Enable full observability with structured logs, metrics, and event tracking. API Platform Cloud empowers teams to build, secure, and scale modern APIs faster, while reducing operational complexity and enabling AI-powered innovation at every stage of the API lifecycle. diff --git a/en/docs/cloud/mcp-servers/browse-mcp-hub.md b/en/docs/cloud/mcp-servers/browse-mcp-hub.md index 36469a1d..b49808ff 100644 --- a/en/docs/cloud/mcp-servers/browse-mcp-hub.md +++ b/en/docs/cloud/mcp-servers/browse-mcp-hub.md @@ -15,13 +15,13 @@ The MCP Hub is the visual catalog for your organization's MCP registry. Use it t The Hub displays the list of all MCP servers registered in your organization's registry. Each card shows the server name, version, description, and any tags. -## Step 2: View a Server +## Step 2: View a server Click a server card to open its detail page. You can view the MCP server details, including its tools, resources, prompts, and connection configuration. ![Everything MCP Server detail page showing MCP Server URL, expandable tools list with echo, add, viewPizzaMenu, and orderPizza, and MCP Server Configuration JSON snippet](../../assets/img/ai-gateway/ai-workspace/mcp-proxies/mcphub-mcp-overview.png) -## Step 3: Explore Capabilities +## Step 3: Explore capabilities Scroll down to the capabilities section. The server's tools, resources, and prompts are listed in expandable panels. @@ -29,7 +29,7 @@ Scroll down to the capabilities section. The server's tools, resources, and prom - **Resources**: Each resource panel shows the resource name, description, URI, and MIME type. - **Prompts**: Each prompt panel shows the prompt name, description, and the arguments it accepts. -## Related Topics +## Related topics - [What is an MCP Registry?](./mcp-registry.md) - [Publish MCP Proxies](./publish-mcp-proxies.md) diff --git a/en/docs/cloud/mcp-servers/design-mcp-servers.md b/en/docs/cloud/mcp-servers/design-mcp-servers.md index f3b3ea1c..a8f566bd 100644 --- a/en/docs/cloud/mcp-servers/design-mcp-servers.md +++ b/en/docs/cloud/mcp-servers/design-mcp-servers.md @@ -11,11 +11,11 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Design and Publish MCP Servers +# Design and publish MCP servers ## Prerequisites -### Create an Organization +### Create an organization If you're signing in to the API Platform Console for the first time, create an organization. @@ -26,7 +26,7 @@ If you're signing in to the API Platform Console for the first time, create an o This creates the organization and opens the organization home page. -### Create a Project +### Create a project 1. Go to [API Platform Console](https://console.bijira.dev/) and sign in. This opens the organization home page. 2. On the organization home page, click **+ Create Project**. @@ -43,19 +43,19 @@ This creates the organization and opens the organization home page. 4. Click **Create**. This creates the project and takes you to the project home page. -## Create an MCP Server +## Create an MCP server API Platform provides two ways of creating MCP Servers. On the project home page, select **MCP Server** to view the available options. ![Create New page with API Proxy and MCP Server tabs, showing Import API Contract and Start from Existing API Proxy options under Expose APIs as MCP Servers, and a blurred Proxy Existing MCP Servers section](../../assets/img/introduction/mcp/mcp-create-options.png) -### MCP Servers for HTTP backends +### MCP servers for HTTP backends This option lets you create an MCP Server based on any HTTP API you have. ![Create MCP Server from Contract form with name Books MCP, identifier, version, base path, description, External network visibility selected, and target URL fields](../../assets/img/introduction/mcp/mcp-create-from-contract.png) -### MCP Servers for existing API Proxies +### MCP servers for existing API proxies If you select **Start from Existing Proxy**, you will get the following view. Here, you will get the option to select an existing API Proxy in API Platform. @@ -67,7 +67,7 @@ If you select **Start from Existing Proxy**, you will get the following view. He !!!info The MCP Servers created in API Platform currently support **2025-03-16** specification. -## Modify Tools of your MCP Server +## Modify tools of your MCP server You can modify the details of the Tools of your generated MCP Server by navigating to the *Policy* section under the *Develop* menu. The default tool names and descriptions are generated by API Platform based on the information available in the API contract. @@ -84,7 +84,7 @@ The following options are supported when modifying the Tools You have to **redeploy** the MCP Server after saving for the new changes to be reflected in the gateway. -## Test the MCP Server +## Test the MCP server You can test the MCP Server in the development environment before promoting it to production. API Platform provides an **MCP Playground** for this purpose. @@ -104,10 +104,10 @@ You can test the MCP Server in the development environment before promoting it t 5. You can select and call individual tools by providing the parameters if necessary. -## Publish the MCP Server +## Publish the MCP server !!!important - If you already have a Devportal theme published, please republish the theme before publishing the MCP Servers to Devportal. + If you already have a Devportal theme published, republish the theme before publishing the MCP Servers to Devportal. Once you verify that the MCP Server is working as expected in the development environment, you can promote it to production. @@ -126,14 +126,14 @@ Now that your MCP Server is deployed in both development and production environm 2. Click **Publish**. 3. In the Publish MCP Server dialog, click Confirm to proceed with publishing the MCP Server with the specified display name. If you want to change the display name, make the necessary changes and then click Confirm. This changes the lifecycle state to **Published**. -## Discover MCP Servers through Developer Portal +## Discover MCP servers through Developer Portal You can view the published MCP Server via the Developer Portal. In the Lifecycle Management pane, click **Go to DevPortal**. This takes you to the MCP Server published to the API Platform Developer Portal. !!!info - If you need to do MCP specific customization to the Developer portal, please refer the [MCP Hub documentation](./devportal-mcp-hub.md). + If you need to do MCP specific customization to the Developer portal, see the [MCP Hub documentation](./devportal-mcp-hub.md). ![Developer Portal home page with APIs and MCP Servers hero banner, Browse our APIs and Browse our MCP Servers buttons, and Empowering Developers to Build Applications section below](../../assets/img/introduction/mcp/mcp-devportal-landing.png) @@ -143,13 +143,13 @@ Go to the MCP Server listing page using the left navigation menu and select your MCP consumers can discover the available tools through this view. Additionally, sample configurations for setting up the MCP Server with an MCP Client can also be obtained from here. -## Connect the MCP Server with MCP Clients / AI Agents +## Connect the MCP server with MCP clients / AI agents MCP Servers in API Platform are secured by default. To access them, you must subscribe through an application, obtain a valid token, and configure it in your MCP client. -For more information regarding managing applications, please refer [this](../devportal/manage-applications/create-an-application.md). +For more information regarding managing applications, see [Create an application](../devportal/manage-applications/create-an-application.md). -Please refer [this section](../devportal/manage-subscriptions/subscribe-to-an-api.md) to get an idea on how you can manage subscriptions to an application. Subscribing to MCP Servers is similar to how you subscribe to API Proxies. +See [this section](../devportal/manage-subscriptions/subscribe-to-an-api.md) to get an idea on how you can manage subscriptions to an application. Subscribing to MCP Servers is similar to how you subscribe to API Proxies. !!!important If you created the MCP Server using an existing API Proxy, you need to subscribe to both using the same application. diff --git a/en/docs/cloud/mcp-servers/devportal-mcp-hub.md b/en/docs/cloud/mcp-servers/devportal-mcp-hub.md index 81998611..c118d6bf 100644 --- a/en/docs/cloud/mcp-servers/devportal-mcp-hub.md +++ b/en/docs/cloud/mcp-servers/devportal-mcp-hub.md @@ -25,7 +25,7 @@ The default look of your MCP Hub will be as follows. ![MCP Hub theming editor showing color palette fields for background, primary, secondary, text, and gradient colors alongside a preview of the MCP-focused Developer Portal landing page](../../assets/img/introduction/mcp/mcp-devportal-default.png) -A themed MCP Hub could look something like the following. If you want to know more on how you can customize the devportal, please refer to our [manual theming guide](../devportal/theming-devportal-org-level.md) and [theming with AI guide](../devportal/theming-devportal-with-ai.md). +A themed MCP Hub could look something like the following. If you want to know more on how you can customize the devportal, see our [manual theming guide](../devportal/theming-devportal-org-level.md) and [theming with AI guide](../devportal/theming-devportal-with-ai.md). ![Themed MCP Hub theming editor showing purple primary color and preview of Developer Portal with purple hero banner saying Empower your development with our MCP Servers for your AI agents and a Product feature section](../../assets/img/introduction/mcp/mcp-devportal-themed.png) diff --git a/en/docs/cloud/mcp-servers/get-started-with-mcp.md b/en/docs/cloud/mcp-servers/get-started-with-mcp.md index a4610991..a6219af6 100644 --- a/en/docs/cloud/mcp-servers/get-started-with-mcp.md +++ b/en/docs/cloud/mcp-servers/get-started-with-mcp.md @@ -14,7 +14,7 @@ content_type: "overview" # Overview -## What is Model Context Protocol? +## What is model context protocol? MCP is a JSON-RPC–based protocol designed to standardize how applications interact with large language models (LLMs). It enables sharing of contextual information—such as local files, databases, or APIs—with LLMs, while also allowing applications to expose tools and capabilities for AI-driven workflows and integrations. @@ -22,7 +22,7 @@ MCP follows a host–client–server architecture and supports two primary trans For more information, refer to the official [specification](https://modelcontextprotocol.io/introduction). -## Remote MCP Servers with API Platform +## Remote MCP servers with API Platform API Platform now includes support for MCP servers. It provides a complete solution for transforming existing APIs into intelligent, AI-ready tools. With a centralized control plane, API Platform simplifies the entire lifecycle of MCP server management—from creation to discovery—delivering a seamless experience for both API developers and AI agent builders. Additionally, API Platform allows you to customize the developer portal to deliver a tailored, MCP-only experience for your consumers. @@ -35,7 +35,7 @@ In summary, API Platform provides the following capabilities related to MCP. 3. Secure the MCP Servers with OAuth2 security. 4. Customize the Developer portal into an MCP Hub. -## MCP Use Cases with API Platform +## MCP use cases with API Platform - [Design and Publish MCP Servers for your APIs](design-mcp-servers.md) - [Proxy Remote MCP Servers](proxy-remote-servers.md) diff --git a/en/docs/cloud/mcp-servers/mcp-registry-api.md b/en/docs/cloud/mcp-servers/mcp-registry-api.md index e7ed5ee8..b1652be0 100644 --- a/en/docs/cloud/mcp-servers/mcp-registry-api.md +++ b/en/docs/cloud/mcp-servers/mcp-registry-api.md @@ -62,7 +62,7 @@ GET /v0.1/servers/{serverName}/versions/{version} Use the special version value `latest` to resolve the most recently published version. -## Response Shape +## Response shape The response from `GET /v0.1/servers` and the version endpoints follows this structure: @@ -103,7 +103,7 @@ curl "https://mcphub.bijira.dev//registry/v0.1/servers?cursor= Compliance**. - **Component level** - go to a component and open **Insights > Compliance**. -## Organization Level +## Organization level The organization level shows only the **Policy compliance** tab and provides an org-wide overview with: @@ -16,25 +16,25 @@ The organization level shows only the **Policy compliance** tab and provides an - A **Project Compliance** table listing each project with its compliance status and policy violation counts. - A **Policy Compliance** table listing each policy with its status across projects. -## Project Level +## Project level The project level shows two tabs: - **Policy compliance** - two summary charts (**Policy Compliance** and **Artifact Compliance**), an Artifact Compliance table listing each component with its compliance status and violation counts, and a Policy Compliance table listing each policy with its status across components. - **AI Compliance** - results from AI compliance analysis. See [AI Compliance Analysis](#ai-compliance-analysis) below. -## Component Level +## Component level The component level shows two tabs: - **Policy compliance** - two summary charts (**Policy Adherence** and **Ruleset Adherence**), a rule violations detail view, a Policy Adherence Summary table, and a Rulesets Adherence Summary table. - **AI Compliance** - results from AI compliance analysis. See [AI Compliance Analysis](#ai-compliance-analysis) below. -## AI Compliance Analysis +## AI compliance analysis AI Compliance Analysis is a manually triggered feature that uses AI to analyze your API definitions against the documents uploaded in **Admin > Governance > Documents** and generates a compliance report. Before running an analysis, ensure you have at least one document. See [Govern API Proxies](../governance/govern-api-proxy.md#documents) for instructions on adding documents. -### Run an Analysis +### Run an analysis Analysis is triggered at the **project level** and covers all API components in the project. @@ -66,7 +66,7 @@ Below the Project Summary, each component is listed as an expandable card showin To re-run the analysis at any time, click **Analyze** at the top of the page. -### View Component-Level Results +### View component-level results After a project-level analysis completes, you can drill down into per-component results. Go to the component and open **Insights > Compliance > AI Compliance**. There is no separate trigger at the component level. diff --git a/en/docs/cloud/monitoring-and-insights/insights.md b/en/docs/cloud/monitoring-and-insights/insights.md index 14925815..f231d963 100644 --- a/en/docs/cloud/monitoring-and-insights/insights.md +++ b/en/docs/cloud/monitoring-and-insights/insights.md @@ -19,7 +19,7 @@ Every dashboard supports configurable refresh intervals and time-range filters, ![Insights Overview dashboard showing summary metrics for total requests, errors, LLM traffic, MCP traffic, and API traffic](../../assets/img/monitoring-and-insights/insights-1.png){.cInlineImage-full} -### Summary Metrics +### Summary metrics | Metric | Description | |---|---| @@ -30,27 +30,27 @@ Every dashboard supports configurable refresh intervals and time-range filters, | **MCP Traffic** | Total number of MCP tool call events in the selected time range. This is useful for tracking agent-initiated activity across MCP servers and tools. Click **View Details** to drill down. | | **API Traffic** | Total number of API calls processed across all supported API types. Compare this with LLM and MCP activity to understand the dominant traffic pattern on the platform. Click **View Details** to drill down. | -### Charts and Visualizations +### Charts and visualizations -**Overall Platform Metrics** — Shows traffic, errors, and throttled requests over time. Use it to see whether spikes in traffic align with failures or throttling, and to distinguish between demand-related issues and more isolated failures. +**Overall platform metrics** — Shows traffic, errors, and throttled requests over time. Use it to see whether spikes in traffic align with failures or throttling, and to distinguish between demand-related issues and more isolated failures. -**Consumer Onboarding Trend** — Tracks new consumer registrations over time. This is useful for understanding growth, measuring the effect of onboarding or product changes, and identifying whether increased traffic is being driven by new adoption. +**Consumer onboarding trend** — Tracks new consumer registrations over time. This is useful for understanding growth, measuring the effect of onboarding or product changes, and identifying whether increased traffic is being driven by new adoption. -**Top Applications** — Ranks applications by traffic volume so you can identify the consumers generating the most load. This is particularly helpful when planning capacity, investigating noisy consumers, or prioritizing customer-facing support. +**Top applications** — Ranks applications by traffic volume so you can identify the consumers generating the most load. This is particularly helpful when planning capacity, investigating noisy consumers, or prioritizing customer-facing support. -**Top APIs Across Platform** — Highlights the most frequently called APIs across all traffic types. This helps you identify which APIs are most critical to day-to-day traffic and therefore most important for reliability, optimization, and incident response. +**Top APIs across platform** — Highlights the most frequently called APIs across all traffic types. This helps you identify which APIs are most critical to day-to-day traffic and therefore most important for reliability, optimization, and incident response. -**Traffic Breakdown** — A pie chart showing the proportion of total traffic by gateway type — LLM, MCP, and API. Use this to understand how traffic is distributed across your platform. +**Traffic breakdown** — A pie chart showing the proportion of total traffic by gateway type — LLM, MCP, and API. Use this to understand how traffic is distributed across your platform. -**Traffic Intensity (Day vs Hour)** — Displays request volume by day of week and hour of day. Use it to spot recurring usage patterns, plan maintenance windows, and prepare infrastructure for predictable peak periods. +**Traffic intensity (day vs hour)** — Displays request volume by day of week and hour of day. Use it to spot recurring usage patterns, plan maintenance windows, and prepare infrastructure for predictable peak periods. -**Top Platforms** — Shows the distribution of operating systems used by consumers. This helps you understand the client environments accessing your platform and can inform client compatibility or support decisions. +**Top platforms** — Shows the distribution of operating systems used by consumers. This helps you understand the client environments accessing your platform and can inform client compatibility or support decisions. -**Top User Agents** — Breaks down request traffic by HTTP user agent so you can distinguish browser, SDK, and automated traffic. It is useful when you want to understand how users and integrations are interacting with your platform. +**Top user agents** — Breaks down request traffic by HTTP user agent so you can distinguish browser, SDK, and automated traffic. It is useful when you want to understand how users and integrations are interacting with your platform. -**Average Latency over Time** — Tracks average response latency across the platform. Sustained increases can point to backend degradation, upstream issues, or load-related performance problems that require deeper investigation. +**Average latency over time** — Tracks average response latency across the platform. Sustained increases can point to backend degradation, upstream issues, or load-related performance problems that require deeper investigation. -**Geo Map** — Shows where requests originate geographically. Switch between **Density Heatmap** and **Metric Heatmap** views. This can help with decisions around regional deployments, CDN placement, compliance planning, and understanding where user demand is concentrated. +**Geo map** — Shows where requests originate geographically. Switch between **Density Heatmap** and **Metric Heatmap** views. This can help with decisions around regional deployments, CDN placement, compliance planning, and understanding where user demand is concentrated. --- @@ -58,7 +58,7 @@ Every dashboard supports configurable refresh intervals and time-range filters, The APIs section provides analytics by API type, covering REST, Async, GraphQL, gRPC, and SOAP traffic. These dashboards help you understand not just how much API traffic the platform is handling, but also which protocol types are most active, where errors are concentrated, and how performance changes across different API styles. -### All APIs Analytics +### All APIs analytics The All APIs Analytics dashboard combines traffic from every API type into a single view. It is the right dashboard to use when you want to compare traffic behavior across protocols before drilling into a specific API style such as REST or GraphQL. @@ -68,7 +68,7 @@ This dashboard is useful for questions such as: - Is an increase in latency affecting all API traffic or only a subset? - Are failures spread across the platform or concentrated in one type of API? -#### Summary Metrics +#### Summary metrics | Metric | Description | |---|---| @@ -77,7 +77,7 @@ This dashboard is useful for questions such as: | **Error Rate** | Percentage of API requests that resulted in an error. This helps you determine whether failures are isolated or widespread across API traffic. | | **Unique Consumers** | Number of distinct users or applications making API calls. This indicates how broadly the APIs are being used across your consumer base. | -#### API Type Breakdown +#### API type breakdown Cards for each protocol type let you quickly compare relative traffic volumes and navigate to the corresponding drill-down views: @@ -89,29 +89,29 @@ Cards for each protocol type let you quickly compare relative traffic volumes an | **gRPC API Traffic** | Number of gRPC remote procedure calls. | | **SOAP API Traffic** | Number of SOAP/XML web service calls. | -#### Charts and Visualizations +#### Charts and visualizations -**Traffic Volume over Time** — Shows request count and average latency on the same chart, making it easier to correlate traffic growth with performance changes. It is especially helpful for checking whether rising usage is contributing to slower responses. +**Traffic volume over time** — Shows request count and average latency on the same chart, making it easier to correlate traffic growth with performance changes. It is especially helpful for checking whether rising usage is contributing to slower responses. -**Error Type Breakdown** — Breaks errors into categories so you can quickly identify the most common failure type. This gives you an immediate sense of whether issues are mostly related to authentication, client behavior, backend systems, or other causes. +**Error type breakdown** — Breaks errors into categories so you can quickly identify the most common failure type. This gives you an immediate sense of whether issues are mostly related to authentication, client behavior, backend systems, or other causes. -**Error Rate Trend** — Shows how the error rate changes over time. This is especially useful for spotting regressions after deployments, validating fixes, and identifying intermittent issues that may not appear in aggregate metrics. +**Error rate trend** — Shows how the error rate changes over time. This is especially useful for spotting regressions after deployments, validating fixes, and identifying intermittent issues that may not appear in aggregate metrics. ![All APIs Analytics dashboard showing traffic volume, error type breakdown, and error rate trend charts](../../assets/img/monitoring-and-insights/insights-4.png){.cInlineImage-full} -**Traffic Intensity (Day vs Hour)** — Highlights when demand is highest by showing request volume by day and hour. Use it to understand recurring demand patterns and to align scaling or maintenance activities with real usage behavior. +**Traffic intensity (day vs hour)** — Highlights when demand is highest by showing request volume by day and hour. Use it to understand recurring demand patterns and to align scaling or maintenance activities with real usage behavior. -**Top Platforms** — A pie chart showing the distribution of API calls by client platform. +**Top platforms** — A pie chart showing the distribution of API calls by client platform. -**Top User Agents** — A pie chart showing the distribution of API calls by user agent. +**Top user agents** — A pie chart showing the distribution of API calls by user agent. -### REST API Analytics +### REST API analytics The REST API Analytics dashboard is a protocol-specific drill-down for REST traffic. You can open this dashboard by clicking the **REST API Traffic** card in the **All APIs Analytics** dashboard. It includes API-level filtering, HTTP status analysis, cache performance metrics, and geographic usage patterns so you can understand how REST APIs are being consumed and where operational issues may be emerging. Because REST traffic often represents the largest share of gateway traffic, this dashboard is particularly useful for day-to-day operational monitoring, troubleshooting client-facing issues, and identifying optimization opportunities. -#### Summary Metrics +#### Summary metrics | Metric | Description | |---|---| @@ -120,46 +120,46 @@ Because REST traffic often represents the largest share of gateway traffic, this | **Error Rate** | Percentage of REST requests that returned an error. This helps you quickly determine whether consumers are experiencing failures at a significant rate. | | **Unique Consumers** | Number of distinct consumers calling REST APIs. This reflects how widely REST APIs are being adopted across applications and users. | -#### Charts and Visualizations +#### Charts and visualizations -**Traffic Volume over Time** — Shows REST request volume together with latency so you can spot periods where rising demand may be affecting performance. This is one of the quickest ways to identify whether slowdowns are traffic-related. +**Traffic volume over time** — Shows REST request volume together with latency so you can spot periods where rising demand may be affecting performance. This is one of the quickest ways to identify whether slowdowns are traffic-related. -**Error Type Breakdown** — Categorizes REST errors to help determine whether failures are caused by authentication issues, invalid requests, rate limiting, or server-side problems. +**Error type breakdown** — Categorizes REST errors to help determine whether failures are caused by authentication issues, invalid requests, rate limiting, or server-side problems. -**Error Rate Trend** — Shows how REST error levels change over time, making it easier to pinpoint when a problem started and whether it is improving or worsening. +**Error rate trend** — Shows how REST error levels change over time, making it easier to pinpoint when a problem started and whether it is improving or worsening. ![REST API Analytics dashboard showing traffic volume, error rate trend, and HTTP status code breakdown](../../assets/img/monitoring-and-insights/insights-5.png){.cInlineImage-full} -**Traffic Intensity (Day vs Hour)** — Displays peak usage periods for REST consumers by day and hour. This helps you understand normal traffic rhythm and identify the best times for maintenance or load testing. +**Traffic intensity (day vs hour)** — Displays peak usage periods for REST consumers by day and hour. This helps you understand normal traffic rhythm and identify the best times for maintenance or load testing. -**HTTP Status Codes over Time** — Breaks responses into `2xx`, `4xx`, and `5xx` classes so you can separate successful requests from client-side and server-side failures. This is useful for determining whether a problem is caused by consumer behavior or backend instability. +**HTTP status codes over time** — Breaks responses into `2xx`, `4xx`, and `5xx` classes so you can separate successful requests from client-side and server-side failures. This is useful for determining whether a problem is caused by consumer behavior or backend instability. -**Application Usage Detail** — Lists the applications using the REST APIs, along with owner, usage count, error rate, and average latency. This helps identify which consumers are generating the most load, which ones are seeing the most errors, and which integrations may require follow-up. +**Application usage detail** — Lists the applications using the REST APIs, along with owner, usage count, error rate, and average latency. This helps identify which consumers are generating the most load, which ones are seeing the most errors, and which integrations may require follow-up. -**REST API Usage over Time** — Shows traffic trends for individual REST APIs, making it easier to track which APIs are growing, declining, or behaving unusually. It is useful when investigating issues affecting a specific API rather than the entire REST layer. +**REST API usage over time** — Shows traffic trends for individual REST APIs, making it easier to track which APIs are growing, declining, or behaving unusually. It is useful when investigating issues affecting a specific API rather than the entire REST layer. -**Cache Hit Percentage** — Tracks total hits, cache hits, and hit percentage over time. Higher cache hit rates usually reduce backend load and improve response times, so this chart helps you understand whether caching is working effectively. +**Cache hit percentage** — Tracks total hits, cache hits, and hit percentage over time. Higher cache hit rates usually reduce backend load and improve response times, so this chart helps you understand whether caching is working effectively. -**Cache Latency** — Shows the latency associated with cached responses so you can understand the performance benefit of caching and whether cached responses are materially improving user experience. +**Cache latency** — Shows the latency associated with cached responses so you can understand the performance benefit of caching and whether cached responses are materially improving user experience. -**Top Platforms** — Shows the operating systems used by REST API consumers. This gives you a better understanding of the environments from which REST traffic originates. +**Top platforms** — Shows the operating systems used by REST API consumers. This gives you a better understanding of the environments from which REST traffic originates. -**Top User Agents** — Shows the HTTP clients, browsers, SDKs, or tools making REST API calls. This can be helpful when diagnosing traffic patterns tied to a specific client or integration. +**Top user agents** — Shows the HTTP clients, browsers, SDKs, or tools making REST API calls. This can be helpful when diagnosing traffic patterns tied to a specific client or integration. -**Geo Map** — Displays the geographic origin of REST API traffic, with support for both **Density Heatmap** and **Metric Heatmap** views. Use it to understand regional demand and identify whether location-specific patterns are affecting usage or performance. +**Geo map** — Displays the geographic origin of REST API traffic, with support for both **Density Heatmap** and **Metric Heatmap** views. Use it to understand regional demand and identify whether location-specific patterns are affecting usage or performance. !!! note Clicking any API type traffic card (**REST**, **Async**, **GraphQL**, **gRPC**, or **SOAP**) in the **All APIs Analytics** dashboard opens a drill-down dashboard for that protocol. Each drill-down follows the same layout as the REST API Analytics dashboard described above. --- -## LLM APIs Analytics +## LLM APIs analytics The LLM APIs Analytics dashboard provides observability for LLM usage on API Platform. It helps you track provider and model adoption, token consumption, estimated cost, latency, guardrail activity, and semantic cache performance. This dashboard is especially useful for teams building AI-powered experiences because it combines operational insight with cost visibility. Instead of looking only at traffic volume, you can also understand how requests are distributed across providers and models, how much those requests are costing, and whether safeguards such as guardrails or semantic caching are working as expected. -### Summary Metrics +### Summary metrics | Metric | Description | |---|---| @@ -170,39 +170,39 @@ This dashboard is especially useful for teams building AI-powered experiences be | **Estimated Cost** | Approximate cost of token usage based on provider pricing. This helps you connect usage growth to financial impact. | | **Average Latency** | Mean end-to-end response time for LLM requests. This is important for understanding user-perceived responsiveness in AI-assisted features. | -### Charts and Visualizations +### Charts and visualizations -**Requests by Provider** — Shows request volume by LLM provider so you can understand provider distribution and traffic share. This is useful when comparing vendor usage, planning failover strategies, or managing commercial dependencies. +**Requests by provider** — Shows request volume by LLM provider so you can understand provider distribution and traffic share. This is useful when comparing vendor usage, planning failover strategies, or managing commercial dependencies. -**Traffic Share by Model** — Shows how traffic is distributed across models, helping you monitor adoption and dependency on specific models. It can also help you identify whether expensive or experimental models are being used more heavily than expected. +**Traffic share by model** — Shows how traffic is distributed across models, helping you monitor adoption and dependency on specific models. It can also help you identify whether expensive or experimental models are being used more heavily than expected. -**Guardrail Triggers** — Shows how often each guardrail is triggered. This can help you tune thresholds, identify recurring policy issues, and understand whether requests are frequently being blocked or altered by safety controls. +**Guardrail triggers** — Shows how often each guardrail is triggered. This can help you tune thresholds, identify recurring policy issues, and understand whether requests are frequently being blocked or altered by safety controls. -**Token Usage over Time (Prompt vs Completion)** — Separates prompt and completion token usage over time so you can better understand input and output patterns. This is useful for identifying cases where prompts are too large, responses are unexpectedly verbose, or usage is growing inefficiently. +**Token usage over time (prompt vs completion)** — Separates prompt and completion token usage over time so you can better understand input and output patterns. This is useful for identifying cases where prompts are too large, responses are unexpectedly verbose, or usage is growing inefficiently. -**Error Type Breakdown** — Categorizes LLM errors to help determine whether failures come from policy violations, authentication problems, rate limits, or provider-side issues. +**Error type breakdown** — Categorizes LLM errors to help determine whether failures come from policy violations, authentication problems, rate limits, or provider-side issues. -**Cost Trend (Estimated USD)** — Tracks estimated LLM spend over time for budgeting, anomaly detection, and cost forecasting. This is especially useful when adoption is growing and cost needs to be monitored closely. +**Cost trend (estimated USD)** — Tracks estimated LLM spend over time for budgeting, anomaly detection, and cost forecasting. This is especially useful when adoption is growing and cost needs to be monitored closely. -**Request Intensity (Day vs Hour)** — Shows when AI features are used most heavily by mapping request volume across days and hours. Use it to understand peak demand windows and align scaling or cost controls accordingly. +**Request intensity (day vs hour)** — Shows when AI features are used most heavily by mapping request volume across days and hours. Use it to understand peak demand windows and align scaling or cost controls accordingly. -**Latency Trend (P90, Median)** — Shows both median and tail latency, helping you spot user experience issues that averages may hide. Tail latency is particularly important for conversational or interactive AI features. +**Latency trend (P90, median)** — Shows both median and tail latency, helping you spot user experience issues that averages may hide. Tail latency is particularly important for conversational or interactive AI features. -**Slowest Models** — Lists models by average latency, along with provider and error counts, so you can identify underperforming models and make better decisions about model selection. +**Slowest models** — Lists models by average latency, along with provider and error counts, so you can identify underperforming models and make better decisions about model selection. -**Semantic Cache Hit Ratio** — Shows the overall cache efficiency. A high ratio means similar prompts are being served from cache, reducing both latency and cost while improving consistency for repeated requests. +**Semantic cache hit ratio** — Shows the overall cache efficiency. A high ratio means similar prompts are being served from cache, reducing both latency and cost while improving consistency for repeated requests. -**Semantic Cache Hit Over Time** — Shows how cache effectiveness changes over time as prompt patterns evolve. This helps you understand whether semantic caching is becoming more or less useful as user behavior changes. +**Semantic cache hit over time** — Shows how cache effectiveness changes over time as prompt patterns evolve. This helps you understand whether semantic caching is becoming more or less useful as user behavior changes. --- -## MCP Analytics +## MCP analytics The MCP Analytics dashboard provides visibility into Model Context Protocol server activity. It helps you monitor tool call volume, consumer sessions, error rates, and traffic distribution across MCP servers and clients. This dashboard is useful when AI agents or MCP-enabled clients are interacting with tools exposed through your platform. It helps you understand which tools are being used most often, whether agents are succeeding or failing, and how activity is distributed across MCP servers and client environments. -### Summary Metrics +### Summary metrics | Metric | Description | |---|---| @@ -211,20 +211,20 @@ This dashboard is useful when AI agents or MCP-enabled clients are interacting w | **Error Rate** | Percentage of MCP tool calls that resulted in an error. Use this to monitor the reliability of tool execution across MCP interactions. | | **Unique Sessions** | Number of distinct MCP sessions, typically representing individual agent or client interactions. This helps you estimate how many separate MCP conversations or runs are taking place. | -### Charts and Visualizations +### Charts and visualizations -**Traffic Volume over Time** — Shows MCP event count together with latency so you can identify spikes in activity or slower tool execution. This is useful when diagnosing whether increased tool usage is affecting response time. +**Traffic volume over time** — Shows MCP event count together with latency so you can identify spikes in activity or slower tool execution. This is useful when diagnosing whether increased tool usage is affecting response time. -**Top Tools by Calls** — Ranks MCP tools by invocation count, helping you identify heavily used tools and prioritize reliability improvements, performance tuning, or governance around the most critical tools. +**Top tools by calls** — Ranks MCP tools by invocation count, helping you identify heavily used tools and prioritize reliability improvements, performance tuning, or governance around the most critical tools. -**Unique Consumers over Time** — Tracks how the number of distinct MCP consumers changes over time, which is useful for measuring adoption and understanding whether MCP usage is expanding across teams or integrations. +**Unique consumers over time** — Tracks how the number of distinct MCP consumers changes over time, which is useful for measuring adoption and understanding whether MCP usage is expanding across teams or integrations. -**Traffic Intensity (Day vs Hour)** — Shows when agents are most active by mapping tool call volume across days and hours. This helps you understand agent behavior patterns and identify periods of concentrated tool usage. +**Traffic intensity (day vs hour)** — Shows when agents are most active by mapping tool call volume across days and hours. This helps you understand agent behavior patterns and identify periods of concentrated tool usage. -**Error Rate Trend** — Shows how MCP error levels change over time so you can correlate spikes with tool changes, client behavior changes, or upstream outages. +**Error rate trend** — Shows how MCP error levels change over time so you can correlate spikes with tool changes, client behavior changes, or upstream outages. -**Error Type Breakdown** — Categorizes MCP errors, including parse errors, invalid requests, missing methods, invalid parameters, internal errors, and server errors. This helps you distinguish malformed client requests from implementation gaps or server-side failures. +**Error type breakdown** — Categorizes MCP errors, including parse errors, invalid requests, missing methods, invalid parameters, internal errors, and server errors. This helps you distinguish malformed client requests from implementation gaps or server-side failures. -**Server Distribution** — Shows which MCP servers are handling traffic so you can understand load distribution across your MCP server fleet and identify over-reliance on a particular server. +**Server distribution** — Shows which MCP servers are handling traffic so you can understand load distribution across your MCP server fleet and identify over-reliance on a particular server. -**Client Distribution** — Shows the distribution of MCP clients by type, helping you identify which runtimes or development environments are driving usage and where MCP adoption is strongest. +**Client distribution** — Shows the distribution of MCP clients by type, helping you identify which runtimes or development environments are driving usage and where MCP adoption is strongest. diff --git a/en/docs/cloud/monitoring-and-insights/integrate-bijira-with-moesif.md b/en/docs/cloud/monitoring-and-insights/integrate-bijira-with-moesif.md index 6769297a..057d154d 100644 --- a/en/docs/cloud/monitoring-and-insights/integrate-bijira-with-moesif.md +++ b/en/docs/cloud/monitoring-and-insights/integrate-bijira-with-moesif.md @@ -1,6 +1,6 @@ # Integrate API Platform with Moesif -Moesif is an API analytics and monetization service that helps you grow your API products. You can integrate API Platform with Moesif and gain valuable insights into your API's usage. While Moesif's API analytics capabilities empower you to make informed decision-making on behalf of your organization, its monetization options simplify revenue generation from your APIs, eliminating the need for complex coding. +Moesif is an API analytics and monetization service that helps you grow your API products. You can integrate API Platform with Moesif and gain valuable insights into your API's usage. While Moesif's API analytics capabilities empower you to make informed decision-making on behalf of your organization, its monetization options simplify revenue generation from your APIs, eliminating the need for complex coding. In this guide, you will: @@ -65,7 +65,7 @@ Once you successfully add the key, you will see a delete option next to it. Curr Once you configure the Moesif API key on API Platform, **wait for five minutes before you publish any data to the Moesif** API analytics platform. -## Step 3: Invoke an API and observe the data on the Moesif Dashboard +## Step 3: Invoke an API and observe the data on the Moesif dashboard You have configured API Platform to publish data to Moesif. Let's see how you can view the insights on Moesif. diff --git a/en/docs/cloud/monitoring-and-insights/status-page.md b/en/docs/cloud/monitoring-and-insights/status-page.md index a4c895b3..ec4612bf 100644 --- a/en/docs/cloud/monitoring-and-insights/status-page.md +++ b/en/docs/cloud/monitoring-and-insights/status-page.md @@ -1,4 +1,4 @@ -# API Platform Status Page +# API Platform status page The **API Platform Status Page** is the official, public source of truth for the real-time operational health of WSO2 API Platform Cloud. It provides live availability information for the platform's services across all regions, so you can quickly confirm whether an issue you are seeing is caused by an ongoing platform incident. diff --git a/en/docs/cloud/samples/samples-overview.md b/en/docs/cloud/samples/samples-overview.md index 1824aaa6..6b610de5 100644 --- a/en/docs/cloud/samples/samples-overview.md +++ b/en/docs/cloud/samples/samples-overview.md @@ -1,4 +1,4 @@ -# Samples Overview +# Samples overview API Platform provides an extensive collection of samples for a wide range of use cases. You can quickly deploy and explore these samples to easily understand the core functionalities of the platform. diff --git a/en/docs/cloud/test-api-proxy/api-chat.md b/en/docs/cloud/test-api-proxy/api-chat.md index 6b2dbd99..c113c8b7 100644 --- a/en/docs/cloud/test-api-proxy/api-chat.md +++ b/en/docs/cloud/test-api-proxy/api-chat.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Test APIs with API Platform API Chat +# Test APIs with API Platform API chat Testing APIs is an essential step in the API development process. API Platform simplifies the testing task by allowing you to engage with your APIs using natural language through API Platform API Chat. It eliminates manual test scenario creation and JSON payload accuracy concerns. It enables easy API communication using human language and requires no coding for handling sequences with multiple resource calls. This makes your API testing efficient and user-friendly. diff --git a/en/docs/cloud/test-api-proxy/graphql-console.md b/en/docs/cloud/test-api-proxy/graphql-console.md index 7b506a51..da33308a 100644 --- a/en/docs/cloud/test-api-proxy/graphql-console.md +++ b/en/docs/cloud/test-api-proxy/graphql-console.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Test GraphQL APIs via the GraphQL Console +# Test GraphQL APIs via the GraphQL console API Platform offers an integrated GraphQL Console to test GraphQL API proxies that you create and deploy. Since API Platform secures APIs with OAuth 2.0 authentication, the GraphQL Console generates test keys to help you invoke your GraphQL operations. diff --git a/en/docs/cloud/test-api-proxy/openapi-console.md b/en/docs/cloud/test-api-proxy/openapi-console.md index f466aad2..9c27ecb1 100644 --- a/en/docs/cloud/test-api-proxy/openapi-console.md +++ b/en/docs/cloud/test-api-proxy/openapi-console.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Test REST Endpoints via the OpenAPI Console +# Test REST endpoints via the openapi console API Platform offers an integrated OpenAPI Console to test REST endpoints for the API proxies you create and deploy. Since API Platform secures REST APIs with OAuth 2.0 authentication, the OpenAPI Console generates test keys to help you test your APIs. diff --git a/en/docs/cloud/test-api-proxy/ws-test-console.md b/en/docs/cloud/test-api-proxy/ws-test-console.md index bea9fa43..d247b503 100644 --- a/en/docs/cloud/test-api-proxy/ws-test-console.md +++ b/en/docs/cloud/test-api-proxy/ws-test-console.md @@ -12,7 +12,7 @@ last_updated: 2026-06-18 content_type: "how-to" --- -# Test WebSocket Endpoints via the WebSocket Console +# Test WebSocket endpoints via the WebSocket console API Platform offers an integrated WebSocket Console to test WebSocket endpoints for the API proxies you create and deploy. Since API Platform secures WebSocket APIs with OAuth 2.0 authentication, the WebSocket Console generates test keys to help you test your APIs. diff --git a/en/docs/cloud/tutorials/expose-a-service-as-a-managed-api.md b/en/docs/cloud/tutorials/expose-a-service-as-a-managed-api.md index ff3545b0..61e2d370 100644 --- a/en/docs/cloud/tutorials/expose-a-service-as-a-managed-api.md +++ b/en/docs/cloud/tutorials/expose-a-service-as-a-managed-api.md @@ -1,6 +1,6 @@ -# Expose a Service as a Managed API +# Expose a service as a managed API -API Platform simplifies securely exposing existing services as managed APIs. It also allows you to manage all aspects of an API's lifecycle, security, throttling, and governance, so you can focus on service development. +API Platform simplifies securely exposing existing services as managed APIs. It also lets you manage all aspects of an API's lifecycle, security, throttling, and governance, so you can focus on service development. In this tutorial, you will use API Platform to expose a service as an API proxy and publish it to the API Platform Developer Portal for application developers to consume. diff --git a/en/docs/cloud/tutorials/secure-an-api-with-role-based-access-control.md b/en/docs/cloud/tutorials/secure-an-api-with-role-based-access-control.md index 9dcb5c94..46333548 100644 --- a/en/docs/cloud/tutorials/secure-an-api-with-role-based-access-control.md +++ b/en/docs/cloud/tutorials/secure-an-api-with-role-based-access-control.md @@ -1,4 +1,4 @@ -# Secure an API with Role-Based Access Control +# Secure an API with role-based access control Role-based access control (RBAC) is a flexible and scalable approach to manage access to API resources. In this approach, each user or group is assigned a specific role that determines the permissions granted to perform operations on an API resource. diff --git a/en/docs/cloud/workflows/configure-workflow-approvals.md b/en/docs/cloud/workflows/configure-workflow-approvals.md index bf7f0469..678bd279 100644 --- a/en/docs/cloud/workflows/configure-workflow-approvals.md +++ b/en/docs/cloud/workflows/configure-workflow-approvals.md @@ -1,4 +1,4 @@ -# Configure Approvals for API Platform Workflows +# Configure approvals for API Platform workflows API Platform allows you to configure approval processes for specific workflows within the platform. An approval process for a workflow ensures that critical or sensitive changes are properly managed and controlled. diff --git a/en/docs/cloud/workflows/review-workflows-requests.md b/en/docs/cloud/workflows/review-workflows-requests.md index 16840a8f..7d7065f5 100644 --- a/en/docs/cloud/workflows/review-workflows-requests.md +++ b/en/docs/cloud/workflows/review-workflows-requests.md @@ -1,4 +1,4 @@ -# Review Workflow Approval Requests +# Review workflow approval requests In API Platform, administrators can [configure approvals for workflows](./configure-workflow-approvals.md) and assign specific users as approvers. diff --git a/en/docs/cloud/workflows/submit-workflow-requests.md b/en/docs/cloud/workflows/submit-workflow-requests.md index 640898db..137e86f4 100644 --- a/en/docs/cloud/workflows/submit-workflow-requests.md +++ b/en/docs/cloud/workflows/submit-workflow-requests.md @@ -1,4 +1,4 @@ -# Submit Workflow Approval Requests +# Submit workflow approval requests In API Platform, if an administrator [configures a workflow to require approval](./configure-workflow-approvals.md), you must submit a request to obtain approval to perform the task. @@ -18,7 +18,7 @@ The approach to request approval can vary depending on the workflow. Click the r To request approval to promote an api proxy from the development environment to production, follow these steps: - 1. Sign in to the [API Platform Console](https://console.Bijira.dev/). + 1. Sign in to the [API Platform Console](https://console.bijira.dev/). 2. In the **api proxy Listing** pane, click on the api proxy you want to deploy. This takes you to the **Overview** page of the api proxy. 3. In the left navigation menu, click **Deploy**. 4. Go to the **Development** card and click **Request to Promote**. @@ -51,7 +51,7 @@ The approach to request approval can vary depending on the workflow. Click the r To request approval to configure a custom URL for an api proxy, follow these steps: - 1. Sign in to the [API Platform Console](https://console.Bijira.dev/). + 1. Sign in to the [API Platform Console](https://console.bijira.dev/). 2. In the **api proxy Listing** pane, click on the api proxy you want to configure. This takes you to the **Overview** page of the api proxy. 3. In the left navigation, click the **Admin** drop-down and then click **Settings**. 4. Click the **URL Settings** tab. This displays the active deployments of the component across different environments and indicates whether a custom URL is configured. diff --git a/en/docs/get-started.md b/en/docs/get-started.md index 83837225..e763edf1 100644 --- a/en/docs/get-started.md +++ b/en/docs/get-started.md @@ -1,5 +1,5 @@ --- -title: "Get Started with WSO2 API Platform" +title: "Get started with WSO2 API Platform" description: "Find the right quick start guide based on your goal: manage and govern APIs, run a standalone gateway, govern AI services, or monetize APIs." canonical_url: https://wso2.com/api-platform/docs/get-started/ md_url: https://wso2.com/api-platform/docs/get-started.md @@ -12,7 +12,7 @@ last_updated: 2026-06-11 content_type: "quickstart" --- -# Get Started +# Get started Not sure where to begin? This page helps you find the right quick start guide based on what you are trying to do. diff --git a/en/docs/guides/ai-and-mcp/build-ai-app-with-claude-code.md b/en/docs/guides/ai-and-mcp/build-ai-app-with-claude-code.md index 4d37c4db..8b8b2208 100644 --- a/en/docs/guides/ai-and-mcp/build-ai-app-with-claude-code.md +++ b/en/docs/guides/ai-and-mcp/build-ai-app-with-claude-code.md @@ -1,4 +1,4 @@ -# Build an AI App with Claude Code that Calls Governed Backend APIs +# Build an AI app with Claude Code that calls governed backend APIs ## Overview @@ -6,7 +6,7 @@ This guide shows you how to put a governed API perimeter in front of Claude Code --- -## Key Concepts +## Key concepts Before you start, here are the WSO2 API Platform terms this guide uses: @@ -68,7 +68,7 @@ Claude Code generates Python code that calls `api_client.py` for every API reque --- -## Step 1: Create an Organization and Project +## Step 1: Create an organization and project Go to the [API Platform Console](https://console.bijira.dev) and sign in with your Google, GitHub, or Microsoft account. @@ -95,7 +95,7 @@ Once you're on the organization home page, create a project: --- -## Step 2: Create and Publish the Reading List API Proxy +## Step 2: Create and publish the reading list API proxy The WSO2 Reading List API is a sample REST API that manages a list of books. You'll expose it as a managed API proxy so WSO2 API Platform can enforce authentication and rate limits on every request. @@ -131,7 +131,7 @@ Promote it to production and publish it: --- -## Step 3: Add a Subscription in the Developer Portal +## Step 3: Add a subscription in the Developer Portal An application gives Claude Code a dedicated identity in WSO2 API Platform. Keeping it separate from your other applications means you can revoke Claude Code's access instantly without affecting anything else. @@ -150,7 +150,7 @@ An application gives Claude Code a dedicated identity in WSO2 API Platform. Keep --- -## Step 4: Create the Project Directory +## Step 4: Create the project directory Create the directory structure Claude Code will work in. Claude Code picks up `CLAUDE.md` and `.claude/settings.json` automatically when you run `claude` from inside the project directory. @@ -422,7 +422,7 @@ Claude Code asks for your approval before executing any code. Review what it pla --- -## What You Learned +## What you learned - Put a governed API perimeter in front of Claude Code so every request is authenticated, rate-limited, and audited by WSO2 API Platform - Gave Claude Code a dedicated application identity that you can revoke instantly without affecting any other application @@ -431,7 +431,7 @@ Claude Code asks for your approval before executing any code. Review what it pla --- -## Next Steps +## Next steps - **[Convert a REST API into an MCP tool and use it in Claude Desktop](convert-rest-api-to-mcp-server.md)** — expose the same Reading List API as an MCP server so Claude Code can use native tool calling instead of the Python helper - **Apply rate limiting to API traffic** — configure per-application and per-subscription rate limits on the Reading List API diff --git a/en/docs/guides/ai-and-mcp/convert-rest-api-to-mcp-server.md b/en/docs/guides/ai-and-mcp/convert-rest-api-to-mcp-server.md index 6c636e7e..364568b1 100644 --- a/en/docs/guides/ai-and-mcp/convert-rest-api-to-mcp-server.md +++ b/en/docs/guides/ai-and-mcp/convert-rest-api-to-mcp-server.md @@ -1,4 +1,4 @@ -# Convert a REST API into an MCP Tool and Use It in Claude Desktop +# Convert a REST API into an MCP tool and use it in Claude Desktop ## Overview @@ -9,7 +9,7 @@ This guide shows you how to expose an existing REST API as a governed MCP server --- -## Key Concepts +## Key concepts Before you start, here are the WSO2 API Platform terms this guide uses: @@ -69,7 +69,7 @@ Claude Desktop only supports local stdio servers. mcp-remote runs locally and br --- -## Step 1: Create an Organization and Project +## Step 1: Create an organization and project Go to the [API Platform Console](https://console.bijira.dev) and sign in with your Google, GitHub, or Microsoft account. @@ -92,7 +92,7 @@ Once you're on the organization home page, create a project: --- -## Step 2: Create the MCP Server +## Step 2: Create the MCP server In this guide, you'll use the Reading List API — a sample REST API that manages a list of books — to create your MCP server. WSO2 API Platform reads the API's OpenAPI spec and generates one tool per operation. No custom server code is required. @@ -117,7 +117,7 @@ When you complete this step, WSO2 API Platform automatically deploys the MCP ser --- -## Step 3: Configure Tool Descriptions +## Step 3: Configure tool descriptions Tool descriptions tell Claude what each tool does and when to use it. The auto-generated descriptions come from the OpenAPI spec's `operationId`, `summary`, and `description` fields — update any that are too technical or too brief. @@ -140,7 +140,7 @@ Click **Save**. Then click **Deploy** from the navigation menu and select **Depl --- -## Step 4: Enable OAuth2 Authentication +## Step 4: Enable OAuth2 authentication Enabling OAuth2 tells the WSO2 MCP Gateway to reject any tool call that doesn't include a valid bearer token. Unauthenticated requests never reach your backend. @@ -155,7 +155,7 @@ In the side menu, scroll to **Deploy** and select **Security Settings**. Toggle --- -## Step 5: Deploy the MCP Server +## Step 5: Deploy the MCP server Deploying promotes your MCP server from the development environment to the production gateway. @@ -169,7 +169,7 @@ Deploying promotes your MCP server from the development environment to the produ --- -## Step 6: Add the MCP Server to the Developer Portal +## Step 6: Add the MCP server to the Developer Portal Publishing makes your MCP server discoverable to consumers in the Developer Portal so they can subscribe and generate credentials. @@ -186,7 +186,7 @@ Publishing makes your MCP server discoverable to consumers in the Developer Port --- -## Step 7: Add a Subscription in the Developer Portal +## Step 7: Add a subscription in the Developer Portal An application in WSO2 API Platform represents a client — in this case, Claude Desktop. You'll create one and subscribe it to the Reading List MCP server so it can make authenticated tool calls. @@ -202,7 +202,7 @@ An application in WSO2 API Platform represents a client — in this case, Claude --- -## Step 8: Create an Access Token +## Step 8: Create an access token Generate the OAuth2 bearer token that Claude Desktop will use to authenticate every tool call. @@ -221,7 +221,7 @@ Generate the OAuth2 bearer token that Claude Desktop will use to authenticate ev --- -## Step 9: Paste the MCP Server Configuration into Claude Desktop +## Step 9: Paste the MCP server configuration into Claude Desktop Claude Desktop only supports local stdio servers via its config file, so you can't point it directly at the WSO2 MCP Gateway URL. mcp-remote solves this — it runs locally as a subprocess, receives calls from Claude Desktop over stdio, and forwards them to the gateway over HTTPS with your bearer token attached. @@ -315,7 +315,7 @@ Claude Desktop loads `claude_desktop_config.json` only on startup. Restart it fu --- -## What You Learned +## What you learned - Created a governed MCP server from a REST API without writing any custom server code - Configured natural-language tool descriptions so Claude understands when to invoke each tool @@ -324,7 +324,7 @@ Claude Desktop loads `claude_desktop_config.json` only on startup. Restart it fu --- -## Next Steps +## Next steps - **Aggregate MCP tools from multiple APIs** — combine this MCP server with others into a single endpoint so AI agents can query across systems in one call - **Connect your MCP server to VS Code Copilot** — use the same deployed MCP server with VS Code Copilot using the Developer Portal's native configuration snippet diff --git a/en/docs/guides/ai-and-mcp/set-up-a-governed-multi-model-llm-proxy-with-cost-controls-and-failover.md b/en/docs/guides/ai-and-mcp/set-up-a-governed-multi-model-llm-proxy-with-cost-controls-and-failover.md index e16943d8..2eb8a247 100644 --- a/en/docs/guides/ai-and-mcp/set-up-a-governed-multi-model-llm-proxy-with-cost-controls-and-failover.md +++ b/en/docs/guides/ai-and-mcp/set-up-a-governed-multi-model-llm-proxy-with-cost-controls-and-failover.md @@ -6,7 +6,7 @@ This guide shows you how to set up a single governed LLM proxy that distributes --- -## Key Concepts +## Key concepts Before you start, here are the WSO2 API Platform terms this guide uses: @@ -385,7 +385,7 @@ After your first request, navigate to **Monitor and Insights** in the **API Plat --- -## What You Learned +## What you learned - Set up a single governed LLM proxy so applications never call the provider directly - Distributed requests across Azure OpenAI models in round-robin order to balance traffic and reduce overloading on any single model @@ -395,7 +395,7 @@ After your first request, navigate to **Monitor and Insights** in the **API Plat --- -## Next Steps +## Next steps **Add prompt injection protection and OWASP coverage** — extend the guardrail configuration with additional security policies to protect against prompt injection and other LLM-specific threats diff --git a/en/docs/index.md b/en/docs/index.md index 97c0070a..734f277b 100644 --- a/en/docs/index.md +++ b/en/docs/index.md @@ -1,5 +1,5 @@ --- -title: "WSO2 API Platform Overview" +title: "WSO2 API Platform overview" description: "Overview of documentation for WSO2 API Platform, the open platform to control APIs, AI, and MCP." canonical_url: https://wso2.com/api-platform/docs/ md_url: https://wso2.com/api-platform/docs/index.md diff --git a/en/docs/llms.txt b/en/docs/llms.txt index f168eaea..2ac16e72 100644 --- a/en/docs/llms.txt +++ b/en/docs/llms.txt @@ -1,13 +1,13 @@ -# WSO2 API Platform Documentation +# WSO2 API Platform documentation > WSO2 API Platform helps you manage, secure, and govern APIs and AI services. It covers the full API lifecycle: from design and deployment to security, monitoring, and monetization. The platform supports REST, WebSocket, and GraphQL APIs as well as LLM (Large Language Model) traffic and MCP (Model Context Protocol) servers for AI agents. It is available as a managed Cloud platform, a Hybrid deployment (cloud control plane, self-hosted gateways), a self-managed API Manager product, and as lightweight standalone gateways. -## Getting Started +## Getting started - [Platform Overview](https://wso2.com/api-platform/docs/index.md): What WSO2 API Platform is, the three deployment options (Cloud, Hybrid, Self-Managed), and the two standalone gateway modes: use this to find the right starting point - [Get Started](https://wso2.com/api-platform/docs/get-started.md): Index of quick start guides organized by use case: manage APIs, run a standalone gateway, govern AI services, or monetize APIs -## Cloud Platform +## Cloud platform - [What is API Platform Cloud?](https://wso2.com/api-platform/docs/cloud/introduction/what-is-bijira.md): Overview of the managed SaaS offering and its core capabilities - [Quick Start: API Proxy](https://wso2.com/api-platform/docs/cloud/introduction/quick-start-guide.md): Create and invoke your first REST API Proxy on the cloud platform in under 10 minutes @@ -16,7 +16,7 @@ - [Projects](https://wso2.com/api-platform/docs/cloud/bijira-concepts/project.md): Logical groupings of APIs and services within an organization - [Data Planes](https://wso2.com/api-platform/docs/cloud/bijira-concepts/data-planes.md): Gateway runtime environments: WSO2-managed (cloud), self-hosted (hybrid), or federated third-party -## Create API Proxies +## Create API proxies - [Create API Proxy Overview](https://wso2.com/api-platform/docs/cloud/create-api-proxy/overview.md): Overview of all creation paths: ingress (My APIs) and egress (Third-Party APIs) - [Create REST API with GenAI](https://wso2.com/api-platform/docs/cloud/create-api-proxy/my-apis/http/create-with-genai.md): Generate a REST API Proxy from a natural language description @@ -52,7 +52,7 @@ - [Azure Content Safety (AI APIs)](https://wso2.com/api-platform/docs/cloud/create-api-proxy/third-party-apis/guardrails/third-party-guardrail-integrations/azure-content-safety-content-moderation.md): Azure Content Safety integration for content moderation on LLM traffic - [AWS Bedrock Guardrail (AI APIs)](https://wso2.com/api-platform/docs/cloud/create-api-proxy/third-party-apis/guardrails/third-party-guardrail-integrations/aws-bedrock-guardrail.md): AWS Bedrock Guardrail integration for content safety on LLM traffic -## Develop API Proxies +## Develop API proxies - [Policy Overview](https://wso2.com/api-platform/docs/cloud/develop-api-proxy/policy/overview.md): Customize an API proxy in the interactive UI: add or remove resources and map resources to backend routes - [Available Policies](https://wso2.com/api-platform/docs/cloud/develop-api-proxy/policy/policies.md): Reference list of all built-in policies for API proxies @@ -68,7 +68,7 @@ - [Secure Gateway-to-Backend with OAuth2](https://wso2.com/api-platform/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-communication-between-bijira-gateway-and-backend-with-oauth2.md): Configure OAuth2 for outbound communication from the gateway to your backend - [Secure Gateway-to-Backend with Mutual TLS](https://wso2.com/api-platform/docs/cloud/develop-api-proxy/authentication-and-authorization/secure-communication-between-the-bijira-gateway-and-your-backend-with-mutual-tls.md): Configure mutual TLS for outbound communication from the gateway to your backend -## Test API Proxies +## Test API proxies - [Test with OpenAPI Console](https://wso2.com/api-platform/docs/cloud/test-api-proxy/openapi-console.md): Interactively test a REST API Proxy using the built-in OpenAPI console - [Test with WebSocket Console](https://wso2.com/api-platform/docs/cloud/test-api-proxy/ws-test-console.md): Test a WebSocket API Proxy using the built-in WebSocket console @@ -76,7 +76,7 @@ - [Test with cURL](https://wso2.com/api-platform/docs/cloud/test-api-proxy/curl.md): Test an API Proxy using cURL commands generated by the platform - [API Chat](https://wso2.com/api-platform/docs/cloud/test-api-proxy/api-chat.md): Test API proxies using a natural language chat interface -## MCP Servers +## MCP servers - [MCP Servers Overview](https://wso2.com/api-platform/docs/cloud/mcp-servers/get-started-with-mcp.md): What MCP is, how the platform supports it, and the three main use cases: design, proxy, and hub - [Design MCP Servers](https://wso2.com/api-platform/docs/cloud/mcp-servers/design-mcp-servers.md): Create MCP servers from HTTP backends or existing API proxies, with auto-generated tool schemas, in-console testing, and publishing @@ -87,7 +87,7 @@ - [Browse the MCP Hub](https://wso2.com/api-platform/docs/cloud/mcp-servers/browse-mcp-hub.md): Discover and connect to MCP servers available in the Developer Portal - [MCP Registry API](https://wso2.com/api-platform/docs/cloud/mcp-servers/mcp-registry-api.md): Programmatic access to the MCP Registry for automated publishing and discovery -## AI Gateway (Cloud) +## AI Gateway (cloud) - [AI Gateway Overview](https://wso2.com/api-platform/docs/cloud/ai-gateway/overview.md): Overview of the cloud-integrated AI Gateway: LLM proxy, MCP proxy, observability, and analytics - [LLM Quick Start Guide](https://wso2.com/api-platform/docs/cloud/ai-gateway/llm/quick-start-guide.md): Set up an LLM proxy to route traffic to an LLM provider with guardrails and rate limiting @@ -171,12 +171,12 @@ - [Theme at API Level](https://wso2.com/api-platform/docs/cloud/devportal/theming-devportal-api-level.md): Apply custom branding to individual API pages in the Developer Portal - [Developer Portal Mode](https://wso2.com/api-platform/docs/cloud/devportal/developer-portal-mode.md): Choose between three display modes: API Portal (APIs only), MCP Hub (MCP servers only), and API & MCP Portal (the default, showing both) -## API Governance +## API governance - [API Governance Overview](https://wso2.com/api-platform/docs/cloud/governance/overview.md): Overview of governance capabilities: design-time linting, policy validation, and compliance checking - [Govern API Proxy](https://wso2.com/api-platform/docs/cloud/governance/govern-api-proxy.md): Apply governance rules and rulesets to an API Proxy -## Self-Hosted and Third-Party Gateways +## Self-hosted and Third-party gateways - [Self-Hosted Gateway Getting Started](https://wso2.com/api-platform/docs/cloud/api-platform-gateway/getting-started.md): Connect a self-hosted gateway to the cloud control plane (hybrid deployment) - [Self-Hosted Gateway Architecture](https://wso2.com/api-platform/docs/cloud/api-platform-gateway/architecture.md): Architecture of a self-hosted gateway connected to the cloud control plane @@ -204,7 +204,7 @@ - [Lifecycle Management (Event Gateway)](https://wso2.com/api-platform/docs/cloud/event-gateway/publish-apis/lifecycle-management.md): Manage lifecycle states for event APIs - [Event Gateway Troubleshooting](https://wso2.com/api-platform/docs/cloud/event-gateway/troubleshooting.md): Diagnose and resolve common Event Gateway issues -## Monitor and Insights +## Monitor and insights - [Logs Overview](https://wso2.com/api-platform/docs/cloud/monitoring-and-insights/logs/overview.md): Overview of logging: runtime logs and audit logs - [Runtime Logs](https://wso2.com/api-platform/docs/cloud/monitoring-and-insights/logs/runtime-logs.md): View and filter real-time API traffic logs @@ -213,7 +213,7 @@ - [Compliance Dashboard](https://wso2.com/api-platform/docs/cloud/monitoring-and-insights/compliance.md): Monitor API governance compliance across your organization - [Integrate with Moesif](https://wso2.com/api-platform/docs/cloud/monitoring-and-insights/integrate-bijira-with-moesif.md): Connect API Platform to Moesif for advanced analytics and monetization -## API Monetization +## API monetization - [API Monetization Overview](https://wso2.com/api-platform/docs/cloud/api-monetization/overview.md): Usage-based API monetization via Stripe and Moesif integration - [Monetization Getting Started](https://wso2.com/api-platform/docs/cloud/api-monetization/getting-started.md): Connect a Stripe account and set up your first paid subscription plan @@ -240,7 +240,7 @@ - [Submit Workflow Approval Requests](https://wso2.com/api-platform/docs/cloud/workflows/submit-workflow-requests.md): How developers submit requests that trigger approval workflows - [Review Workflow Approval Requests](https://wso2.com/api-platform/docs/cloud/workflows/review-workflows-requests.md): How admins review and act on pending approval requests -## Tutorials and Samples +## Tutorials and samples - [Expose a Service as a Managed API](https://wso2.com/api-platform/docs/cloud/tutorials/expose-a-service-as-a-managed-api.md): End-to-end tutorial: expose a backend service as a managed REST API - [Secure an API with RBAC](https://wso2.com/api-platform/docs/cloud/tutorials/secure-an-api-with-role-based-access-control.md): End-to-end tutorial: implement role-based access control on a REST API @@ -252,7 +252,7 @@ - [API Manager Overview](https://wso2.com/api-platform/docs/api-manager/overview.md): WSO2 API Manager: the self-hosted full-stack product for on-premises and air-gapped deployments -## API Gateway (Standalone) +## API Gateway (standalone) - [API Gateway Overview](https://wso2.com/api-platform/docs/api-gateway/overview.md): Overview of the standalone Go-based gateway for REST, WebSocket, and GraphQL APIs - [API Gateway Quick Start](https://wso2.com/api-platform/docs/api-gateway/quick-start-guide.md): Configure your first API Proxy using YAML and start routing traffic @@ -304,7 +304,7 @@ - [Management API: WebBroker API Management](https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/webbroker-api-management.md): REST API reference for creating, listing, retrieving, and deleting WebBroker API configurations in API Platform Gateway - [Management API: Schemas](https://wso2.com/api-platform/docs/api-gateway/gateway-controller-management-api/schemas.md): JSON schema definitions for all API Platform Gateway Controller management API request and response objects -## AI Gateway (Standalone) +## AI Gateway (standalone) - [AI Gateway Overview](https://wso2.com/api-platform/docs/ai-gateway/overview.md): Overview of the standalone AI Gateway: LLM proxy, MCP proxy, deployment, and observability - [LLM Proxy Quick Start](https://wso2.com/api-platform/docs/ai-gateway/llm-proxy/quick-start-guide.md): Deploy the standalone AI Gateway and route your first LLM request @@ -339,7 +339,7 @@ - [AI Gateway Analytics Header Filter](https://wso2.com/api-platform/docs/ai-gateway/analytics/analytics-header-filter.md): Control which request and response headers are sent to analytics backends using allow or deny mode - [AI Gateway Controller Authentication](https://wso2.com/api-platform/docs/ai-gateway/ai-gateway-rest-api/authentication.md): Configure Basic Auth or JWT/IDP authentication and role-based authorization for the AI Gateway Controller REST API -## Policy Hub +## Policy hub - [Policy Hub Overview](https://wso2.com/api-platform/docs/policy-hub/overview.md): Open source repository of API policies and AI guardrails: automatically available to Cloud, API Manager 4.7+, and standalone gateways diff --git a/en/docs/policy-hub/overview.md b/en/docs/policy-hub/overview.md index 66299d6f..8e6cb377 100644 --- a/en/docs/policy-hub/overview.md +++ b/en/docs/policy-hub/overview.md @@ -1,4 +1,4 @@ -# WSO2 API Platform Policy Hub +# WSO2 API Platform policy hub [The Policy Hub](https://wso2.com/api-platform/policy-hub) is the official, curated collection of [gateway policies](../api-gateway/policies/overview.md) for the WSO2 API Platform. It gives you a growing library of production-ready, versioned policy implementations that you can apply to any API or MCP server without writing custom code. @@ -6,13 +6,13 @@ Policies are self-contained units of behavior that plug into the gateway's reque The Policy Hub is powered by an [open source repository on GitHub](https://github.com/wso2/gateway-controllers). Every policy is versioned independently, the full source and documentation live in the repo, and contributions are welcome. For more information about contributing policies, see [Policy Development Guide](https://wso2.com/api-platform/policy-hub/policy-development-guide). -## How Policies Work +## How policies work A policy attaches to an API, covering all operations, or to a specific operation, and runs on the request phase, the response phase, or both. Multiple policies chain together on the same API, each one processing the message in sequence before it reaches the next. The gateway evaluates the chain at runtime. For more information, see [API Platform Policies overview](../api-gateway/policies/overview.md). -## Policy Categories +## Policy categories ### Security @@ -63,7 +63,7 @@ Policies designed specifically for the characteristics of AI APIs — cost, toke | Model Weighted Round Robin | Distributes requests across model endpoints according to configured weights | | Respond | Returns an immediate response without forwarding to the upstream backend | -### MCP (Model Context Protocol) +### MCP (model context protocol) A dedicated policy tier for securing and controlling MCP servers — the emerging standard for exposing tools, resources, and prompts to AI agents. @@ -88,14 +88,14 @@ Modify requests and responses in flight. | JSON/XML Mediator | Converts payloads between JSON and XML formats | | Interceptor Service | Calls a user-defined HTTP service during the request and/or response phase | -### Logging, Analytics, and Monitoring +### Logging, analytics, and monitoring | Policy | What it does | | -- | -- | | Log Message | Logs request/response payload and headers | | Analytics Header Filter | Controls which headers appear in analytics data using allow or deny mode | -## Common Use Cases +## Common use cases __AI guardrails__: Stack prompt-injection detection, PII masking, and a semantic prompt guard on an LLM API to enforce safety and compliance requirements. @@ -107,10 +107,10 @@ __Semantic caching__: Place the Semantic Cache policy on a high-traffic LLM API __Multi-model routing__: Use Model Weighted Round Robin to distribute traffic across model endpoints by weight. -## Independent Versioning +## Independent versioning Every policy in the hub is versioned on its own track. When a new version ships, prior versions remain fully available; so running deployments do not break by upon an update. -## Extending the Hub +## Extending the hub The [API Platform CLI can build a custom gateway image](../api-gateway/policies/custom-policies/building-gateway-with-custom-policies.md) that bundles any combination of hub policies and policies you write yourself. So you can fill your requirement gaps, if any, with local implementations, and contribute them to Policy Hub. \ No newline at end of file diff --git a/en/docs/samples/AI-gateway-and-llm-failover.md b/en/docs/samples/AI-gateway-and-llm-failover.md index dee0a485..40f9431a 100644 --- a/en/docs/samples/AI-gateway-and-llm-failover.md +++ b/en/docs/samples/AI-gateway-and-llm-failover.md @@ -1,4 +1,4 @@ -# LLM Provider and Proxy - AI Policies for privacy and cost control +# LLM provider and proxy - AI policies for privacy and cost control > **Sample source:** [wso2/api-platform-samples/llm-cost-control-and-privacy-control](https://github.com/wso2/api-platform/tree/24298f4d07768e664ee16c5c38f96b9d1b89889e/samples/llm-cost-control-and-privacy-control) > @@ -15,7 +15,7 @@ When your application routes LLM traffic through the WSO2 AI Gateway, you can at --- -## What You Will Learn +## What you will learn By working through this sample you will understand how to: @@ -24,15 +24,15 @@ By working through this sample you will understand how to: --- -## Scenarios Covered +## Scenarios covered -### Scenario 1 — Semantic Cache +### Scenario 1 — semantic cache **Problem:** Identical or near-identical questions (paraphrased, reworded) are sent to the LLM repeatedly, incurring cost and latency on every call. **What this scenario does:** The gateway generates an embedding of each incoming prompt using Mistral and stores the LLM response in Redis. If a subsequent request is ≥ 85% semantically similar to a cached prompt, the cached response is returned immediately — no LLM call is made. -### Scenario 2 — PII Masking +### Scenario 2 — PII masking **Problem:** Users sometimes include personal data (email addresses, phone numbers) in prompts. Sending this data to a third-party LLM provider may violate privacy policies or compliance requirements. @@ -40,11 +40,11 @@ By working through this sample you will understand how to: --- -## Expected Results +## Expected results After running the test scripts you should observe the following for each scenario. -### Scenario 1 — Semantic Cache +### Scenario 1 — semantic cache The same question is sent twice. On the second request, the gateway should return a cached response. **The test detects a cache hit via:** @@ -57,7 +57,7 @@ The same question is sent twice. On the second request, the gateway should retur > If `embedding_provider_api_key` is not set in `additional-config.toml`, cache lookups silently fall through to OpenAI and the test will warn rather than fail. -### Scenario 2 — PII Masking +### Scenario 2 — PII masking A prompt containing a unique email address and phone number is sent, asking the model to repeat them verbatim. Because the gateway redacts the values before forwarding the request, **neither the original email nor the phone number should appear in the response**. @@ -80,9 +80,9 @@ A prompt containing a unique email address and phone number is sent, asking the --- -## Required Configuration +## Required configuration -### 1. OpenAI API Key +### 1. OpenAI API key The setup script injects the key into the LLM provider at deploy time. Provide it via: @@ -99,7 +99,7 @@ export OPENAI_API_KEY="sk-..." The key is never written to disk; it is substituted into the provider payload at runtime and discarded. -### 2. Mistral API Key (required for Scenario 2) +### 2. Mistral API key (required for scenario 2) Open `additional-config.toml` and fill in your Mistral key: @@ -145,7 +145,7 @@ The script performs these steps in order: All steps are idempotent — re-running the script on an already-configured environment is safe. -### Endpoints After Setup +### Endpoints after setup | Endpoint | URL | |---|---| @@ -155,7 +155,7 @@ All steps are idempotent — re-running the script on an already-configured envi --- -## Running the Tests +## Running the tests Each policy has its own script so you can run them independently. All scripts require `jq` and call the gateway proxy directly — no API key is needed at test time (the gateway uses its stored credentials). diff --git a/en/docs/samples/ai-gw-llm-proxy-sample-overview.md b/en/docs/samples/ai-gw-llm-proxy-sample-overview.md index c0859613..d6582ed8 100644 --- a/en/docs/samples/ai-gw-llm-proxy-sample-overview.md +++ b/en/docs/samples/ai-gw-llm-proxy-sample-overview.md @@ -1,4 +1,4 @@ -# LLM Proxy - Token Based Rate Limiting Sample +# LLM proxy - token based rate limiting sample > **Sample source:** [wso2/api-platform — samples/ai-gw-llm-proxy](https://github.com/wso2/api-platform/tree/main/samples/ai-gw-llm-proxy) > @@ -15,7 +15,7 @@ This sample sets up a local Docker stack that demonstrates how the gateway track --- -## What You Will Learn +## What you will learn By working through this sample you will understand: @@ -23,7 +23,7 @@ By working through this sample you will understand: --- -## Scenario - Token Based Rate Limiting on an LLM Proxy +## Scenario - token based rate limiting on an LLM proxy **Problem:** An unprotected LLM proxy allows any caller to send unlimited requests, risking abuse, runaway costs, and provider rate limit violations. @@ -48,11 +48,11 @@ policies: --- -## Expected Results +## Expected results After running `sh test.sh` you should observe the following. -### Token Based Rate Limiting +### Token based rate limiting Two requests are sent back to back using the registered API key. The first request succeeds and the second is rate limited. @@ -121,7 +121,7 @@ The script performs these steps in order: 6. Registers the LLM provider, LLM proxy, and inbound API key via the management API 7. Polls the traffic endpoint until routes are live -### Endpoints After Setup +### Endpoints after setup | Endpoint | URL | |---|---| @@ -132,7 +132,7 @@ The script performs these steps in order: --- -## Try It Manually +## Try it manually Once `setup.sh` completes, you can exercise the gateway directly from your terminal. @@ -167,7 +167,7 @@ curl -sk -w "\n→ HTTP %{http_code}" -X POST https://localhost:8443/assistant/c --- -## Running the Tests +## Running the tests ```bash sh test.sh diff --git a/en/docs/tools/arazzo-mcp-gen-cli/quick-start-guide.md b/en/docs/tools/arazzo-mcp-gen-cli/quick-start-guide.md index df9b5441..a22e5598 100644 --- a/en/docs/tools/arazzo-mcp-gen-cli/quick-start-guide.md +++ b/en/docs/tools/arazzo-mcp-gen-cli/quick-start-guide.md @@ -1,8 +1,8 @@ -## Quick Start — Arazzo MCP Generator (arazzo-mcp-gen) +## Quick start — Arazzo MCP generator (arazzo-mcp-gen) `arazzo-mcp-gen` is a CLI tool that turns an [Arazzo specification](https://spec.openapis.org/arazzo/latest.html) and its referenced OpenAPI files into a fully Dockerized Python MCP (Model Context Protocol) server. Each Arazzo workflow becomes an MCP tool that any AI agent can call. -## What It Does +## What it does Given a folder containing: @@ -55,7 +55,7 @@ arazzo-mcp-gen --version --- -## Quick Start +## Quick start If you don't have an Arazzo spec yet, let the CLI create a sample one: @@ -78,11 +78,11 @@ Once Docker finishes building, run it: docker run -p 5000:5000 ``` -## User Scenario: End-to-End Walkthrough +## User scenario: End-to-End walkthrough > **Scenario:** You have an OpenAPI spec for a pet store API and want to expose a "check if a pet exists, then create or update it" workflow as an MCP tool for an AI agent. -### Step 1 — Prepare your project folder +### Step 1 — prepare your project folder Create a folder containing your Arazzo specification and its referenced OpenAPI files: @@ -96,7 +96,7 @@ pet-project/ └── petstore_openapi.yaml ← Your OpenAPI spec ``` -### Step 2 — Validate the spec +### Step 2 — validate the spec ```bash arazzo-mcp-gen validate -d . @@ -114,7 +114,7 @@ Validation Result: PASSED Fix any errors reported before continuing. Warnings are informational; use `--strict` to treat them as errors in CI. -### Step 3 — Inspect the spec +### Step 3 — inspect the spec ```bash arazzo-mcp-gen inspect -d . @@ -126,7 +126,7 @@ Review the printed summary to confirm: - Every step has an `operationId` that matches your OpenAPI spec - Input schema, success criteria, and routing look correct -### Step 4 — Visualize the flow +### Step 4 — visualize the flow ```bash arazzo-mcp-gen visualize -d . @@ -141,7 +141,7 @@ To save it: arazzo-mcp-gen visualize -d . -o flow.md ``` -### Step 5 — Generate the MCP server +### Step 5 — generate the MCP server Make sure Docker is running, then: @@ -167,7 +167,7 @@ Building Docker image... ╚════════════════════════════════════════════════════════════════════════╝ ``` -### Step 6 — Run the server +### Step 6 — run the server Copy the `docker run` command from the output and run it: @@ -175,7 +175,7 @@ Copy the `docker run` command from the output and run it: docker run -p 5000:5000 pet-upsert-workflow-v3-mcp-server ``` -### Step 7 — Connect an MCP client +### Step 7 — connect an MCP client The server is now live at `http://localhost:5000/mcp` in stateless HTTP mode. To connect it to an MCP client like **Claude Desktop**, you can use `supergateway` to bridge the HTTP endpoint: @@ -201,7 +201,7 @@ The AI agent can now call your Arazzo workflows as tools. The tool executes the --- -## Generated Artifacts +## Generated artifacts Inspect with `--output` / `-o ./artifacts`: diff --git a/en/docs/tools/cli/customizing-gateway-policies.md b/en/docs/tools/cli/customizing-gateway-policies.md index 5e2d6d14..06293736 100644 --- a/en/docs/tools/cli/customizing-gateway-policies.md +++ b/en/docs/tools/cli/customizing-gateway-policies.md @@ -1,6 +1,6 @@ -# Customizing the Gateway by Adding and Removing Policies +# Customizing the gateway by adding and removing policies -## CLI Command +## CLI command ```shell ap gateway image build \ @@ -13,13 +13,13 @@ ap gateway image build \ [--output-dir ] ``` -## Sample Command +## Sample command ```shell ap gateway image build ``` -## Additional Notes for Users +## Additional notes for users Use `ap gateway image build --help` to view detailed usage information for this command. @@ -54,7 +54,7 @@ All other policies are treated as **PolicyHub policies**: Even an output directory is not explicitly specified, the built images are cached by default. On subsequent executions, the cache is cleared and replaced with newly built images. The cache location is displayed in the command output. -### Non-Self-Explanatory Flags +### Non-self-explanatory flags - `--name` (`-n`): Sets the gateway name. If not provided, the current directory name is used by default. - `--path`: Specifies the directory containing `build.yaml`. By default, this is the current working directory. diff --git a/en/docs/tools/cli/quick-start-guide.md b/en/docs/tools/cli/quick-start-guide.md index 65768fa7..1183393b 100644 --- a/en/docs/tools/cli/quick-start-guide.md +++ b/en/docs/tools/cli/quick-start-guide.md @@ -1,4 +1,4 @@ -## Quick Start — API Platform Controller (ap) +## Quick start — API Platform controller (ap) This short guide explains how to use a prebuilt `ap` binary so you can run the CLI from any location. diff --git a/en/docs/tools/cli/reference.md b/en/docs/tools/cli/reference.md index c27c416c..d5feea54 100644 --- a/en/docs/tools/cli/reference.md +++ b/en/docs/tools/cli/reference.md @@ -2,7 +2,7 @@ `ap` is a command-line tool for managing and interacting with the WSO2 API Platform. -## Supported Short Flags +## Supported short flags | Flag | Short Flag | |------------------|------------| @@ -12,11 +12,11 @@ | `--file` | `-f` | | `--version` | `-v` | -## Gateway Sub Commands +## Gateway sub commands > **Note:** Each command supports the `--help` flag for detailed usage information. -## Prerequisites for Gateway Controller Commands +## Prerequisites for gateway controller commands - You must first add and/or select a gateway in the CLI using the appropriate gateway-related commands. - Credentials for a gateway can come from either the gateway configuration (when you add the gateway) or from environment variables. **Environment variables take precedence** over configuration and will override credentials stored in the config when present. @@ -27,15 +27,15 @@ --- -### 1. Add a Gateway +### 1. Add a gateway -#### CLI Command +#### CLI command ```shell ap gateway add --display-name --server [--auth ] ``` -#### Sample Commands +#### Sample commands ```shell # Add a gateway with no authentication (default) @@ -48,7 +48,7 @@ ap gateway add --display-name dev --server http://localhost:9090 --auth basic ap gateway add --display-name prod --server https://api.example.com --auth bearer ``` -#### Authentication Setup +#### Authentication setup For **basic** authentication, export these environment variables (replace the placeholders with your values): ```shell @@ -65,15 +65,15 @@ export WSO2AP_GW_TOKEN= --- -### 2. List Gateways +### 2. List gateways -#### CLI Command +#### CLI command ```shell ap gateway list ``` -#### Sample Command +#### Sample command ```shell ap gateway list @@ -81,15 +81,15 @@ ap gateway list --- -### 3. Remove a Gateway +### 3. Remove a gateway -#### CLI Command +#### CLI command ```shell ap gateway remove --display-name ``` -#### Sample Command +#### Sample command ```shell ap gateway remove --display-name dev @@ -97,15 +97,15 @@ ap gateway remove --display-name dev --- -### 4. Change the Gateway +### 4. Change the gateway -#### CLI Command +#### CLI command ```shell ap gateway use --display-name ``` -#### Sample Command +#### Sample command ```shell ap gateway use --display-name dev @@ -113,15 +113,15 @@ ap gateway use --display-name dev --- -### 5. Check the current Gateway +### 5. Check the current gateway -#### CLI Command +#### CLI command ```shell ap gateway current ``` -#### Sample Command +#### Sample command ```shell ap gateway current @@ -129,15 +129,15 @@ ap gateway current --- -### 6. Returns the health status of the Gateway +### 6. Returns the health status of the gateway -#### CLI Command +#### CLI command ```shell ap gateway health ``` -#### Sample Command +#### Sample command ```shell ap gateway health @@ -145,15 +145,15 @@ ap gateway health --- -### 7. Apply a Resource +### 7. Apply a resource -#### CLI Command +#### CLI command ```shell ap gateway apply --file ``` -#### Sample Command +#### Sample command ```shell ap gateway apply --file petstore-api.yaml @@ -163,13 +163,13 @@ ap gateway apply --file petstore-api.yaml ### 8. List all APIs -#### CLI Command +#### CLI command ```shell ap gateway api list ``` -#### Sample Command +#### Sample command ```shell ap gateway api list @@ -179,14 +179,14 @@ ap gateway api list ### 9. Get a specific API by name and version or id -#### CLI Command +#### CLI command ```shell ap gateway api get --display-name --version --format ap gateway api get --id --format ``` -#### Sample Command +#### Sample command ```shell ap gateway api get --display-name "PetStore API" --version v1.0 --format yaml @@ -197,13 +197,13 @@ ap gateway api get --id sample-1 --format yaml ### 10. Delete an API -#### CLI Command +#### CLI command ```shell ap gateway api delete --id ``` -#### Sample Command +#### Sample command ```shell ap gateway api delete --id @@ -213,7 +213,7 @@ ap gateway api delete --id ### 11. Build a gateway -#### CLI Command +#### CLI command ```shell ap gateway image build \ @@ -231,25 +231,25 @@ ap gateway image build \ [--output-dir ] ``` -#### Sample Command +#### Sample command ```shell ap gateway image build ``` -#### Additional Note for Users +#### Additional note for users Refer to [this document](customizing-gateway-policies.md) for more information. ### 12. List all MCPs -#### CLI Command +#### CLI command ```shell ap gateway mcp list ``` -#### Sample Command +#### Sample command ```shell ap gateway mcp list @@ -259,14 +259,14 @@ ap gateway mcp list ### 13. Retrieves a specific MCP -#### CLI Command +#### CLI command ```shell ap gateway mcp get --display-name --version --format ap gateway mcp get --id --format ``` -#### Sample Command +#### Sample command ```shell ap gateway mcp get --display-name my-mcp --version 1.0.0 --format json @@ -277,13 +277,13 @@ ap gateway mcp get --id sample-id --format json ### 14. Permanently deletes a MCP -#### CLI Command +#### CLI command ```shell ap gateway mcp delete --id ``` -#### Sample Command +#### Sample command ```shell ap gateway mcp delete --id sample-id @@ -293,13 +293,13 @@ ap gateway mcp delete --id sample-id ### 15. Generate MCP -#### CLI Command +#### CLI command ```shell ap gateway mcp generate --server --output ``` -#### Sample Command +#### Sample command ```shell ap gateway mcp generate --server http://localhost:3001/mcp --output target diff --git a/en/docs/tools/vscode-api-design/design-apis.md b/en/docs/tools/vscode-api-design/design-apis.md index 863ae940..0b8d0359 100644 --- a/en/docs/tools/vscode-api-design/design-apis.md +++ b/en/docs/tools/vscode-api-design/design-apis.md @@ -1,4 +1,4 @@ -# Design APIs using API Designer +# Design APIs using API designer You can use API Designer to create and improve your OpenAPI 3.x specification with AI-assisted workflows and form-based editing. @@ -16,7 +16,7 @@ Example prompt: Open your specification file, then open API Designer (see [Getting started](./getting-started.md)). API Designer treats the file as the source of truth and writes updates back to the same file. -### Work in Design view +### Work in design view ![API Designer Design view for Order Management API showing AI Readiness, Security, and REST Compliance score cards, paths list, and Edit with AI button](./images/design-view.png) diff --git a/en/docs/tools/vscode-api-design/end-to-end-tutorial.md b/en/docs/tools/vscode-api-design/end-to-end-tutorial.md index e009184e..a19257c1 100644 --- a/en/docs/tools/vscode-api-design/end-to-end-tutorial.md +++ b/en/docs/tools/vscode-api-design/end-to-end-tutorial.md @@ -24,7 +24,7 @@ Outcome: A working OpenAPI draft on workspace. Note: If Copilot prompts you to open the specification in API Designer, confirm the prompt. -## Step 2: Open API Designer +## Step 2: Open API designer 1. With the openapi spec file (e.g: `orders-api.yaml`) focused, open API Designer using one of these options: - Copilot Chat: Confirm the prompt to open in API Designer (uses the `openInApiDesigner` tool). @@ -82,7 +82,7 @@ Outcome: You can prioritize issues by impact and severity. Outcome: A practical fix backlog. -## Step 7: Fix with AI (Chat + `api-design` skill) +## Step 7: Fix with AI (chat + `api-design` skill) 1. Open **Chat** with the spec available (open editor or `@` file reference, depending on product). 2. Ask for a bounded fix tied to the report, for example: diff --git a/en/docs/tools/vscode-api-design/getting-started.md b/en/docs/tools/vscode-api-design/getting-started.md index f10f0cf7..3b2ca2e2 100644 --- a/en/docs/tools/vscode-api-design/getting-started.md +++ b/en/docs/tools/vscode-api-design/getting-started.md @@ -1,10 +1,10 @@ -# API Designer +# API designer API Designer is a Visual Studio Code extension for building and improving OpenAPI specifications. It helps you use AI to design APIs faster, assess AI readiness, and fix governance issues. ## What you can do -- Design APIs with **Github Copilot** using the built-in **API Design Skill**, with guided recommendations and faster fixes. +- Design APIs with **GitHub Copilot** using the built-in **API Design Skill**, with guided recommendations and faster fixes. - Design and edit OpenAPI specs visually inside VS Code with GitHub Copilot Assistance - Validate APIs against governance and best-practice rulesets - Analyze **AI readiness** and identify improvement areas diff --git a/en/docs/tools/vscode-api-design/govern-apis.md b/en/docs/tools/vscode-api-design/govern-apis.md index 85d2544d..bf8a041f 100644 --- a/en/docs/tools/vscode-api-design/govern-apis.md +++ b/en/docs/tools/vscode-api-design/govern-apis.md @@ -1,4 +1,4 @@ -# Govern APIs using API Designer +# Govern APIs using API designer You can use API Designer to assess and improve your OpenAPI 3.x specification for AI readiness, design quality, and secure production use. @@ -17,7 +17,7 @@ API Designer applies governance checks using Spectral rulesets and AI. You can r - Category-level breakdown to quickly identify weak areas. - Violations grouped by rule, severity, or area of the specification. -## Reports in API Designer +## Reports in API designer API Designer includes the following reports: diff --git a/en/docs/tools/vscode-arazzo-visualizer/getting-started.md b/en/docs/tools/vscode-arazzo-visualizer/getting-started.md index 6e0537bf..5f0776a0 100644 --- a/en/docs/tools/vscode-arazzo-visualizer/getting-started.md +++ b/en/docs/tools/vscode-arazzo-visualizer/getting-started.md @@ -1,19 +1,19 @@ -# Arazzo Visualizer for VS Code +# Arazzo visualizer for VS Code Arazzo Visualizer helps you understand, edit, and run Arazzo Specification workflows directly inside VS Code. It turns Arazzo files into interactive diagrams, keeps the diagram in sync with your code, and includes a built-in runner engine so you can try workflows against real APIs without leaving the editor. -## Quick Start +## Quick start - Install the extension from the VS Code Marketplace. - Open an Arazzo file, such as .arazzo.yaml, .arazzo.yml, or .arazzo.json. - Click the Arazzo Overview icon in the editor toolbar, or open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run ArazzoDesigner: Open Arazzo Visualizer. - The visualizer opens beside your file and updates as you edit. -## Main Features +## Main features -### Visualize Workflows +### Visualize workflows Read complex API flows as a clear diagram instead of scanning long YAML or JSON files. @@ -22,7 +22,7 @@ Read complex API flows as a clear diagram instead of scanning long YAML or JSON - Inspect details: Select a step to understand the request, response, inputs, outputs, and success checks. - Stay in sync: Update the file and the diagram refreshes automatically. -### CodeLens and Quick Actions +### CodeLens and quick actions The extension adds helpful actions above workflow definitions. @@ -30,7 +30,7 @@ The extension adds helpful actions above workflow definitions. - ▶ Try with curl: Execute the workflow directly from the editor and see the result in a terminal. If the workflow has input fields, a panel opens so you can fill them in before running. - ▶ Try with AI: Hand the workflow off to GitHub Copilot and run it through a natural language conversation. -### GitHub Copilot Support +### GitHub Copilot support Arazzo Visualizer works with GitHub Copilot so you can create, change, and run workflows using plain English. @@ -68,7 +68,7 @@ Copilot can also control the runner engine for you. Ask it to start the server, ![Sample Demo](./images/v3_visualizer_demo.gif) -### Run Workflows +### Run workflows The visualizer shows how a workflow is designed. The built-in Runner Engine helps you prove that the workflow actually works. @@ -96,7 +96,7 @@ When you click it, the extension builds the curl request for you, displays the r ![Try with curl Demo](./images/v3_curl_demo.gif) -### Execution Logs +### Execution logs When a workflow runs, the extension shows what happened step by step. @@ -104,7 +104,7 @@ When a workflow runs, the extension shows what happened step by step. - Clear results: See which steps passed, which failed, and why. - Trace details: Review timing and request flow information when you need to troubleshoot a slow or failing workflow. -### Smart Editing Support +### Smart editing support The extension also improves the normal editing experience for Arazzo files. diff --git a/en/mkdocs.yml b/en/mkdocs.yml index da4e18c5..c10d1967 100644 --- a/en/mkdocs.yml +++ b/en/mkdocs.yml @@ -71,38 +71,38 @@ strict: false # Navigation nav: - Overview: index.md - - Get Started: get-started.md + - Get started: get-started.md - Cloud: - Introduction: - What is API Platform Cloud?: cloud/introduction/what-is-bijira.md - - Quick Start Guide: - - API Proxy: cloud/introduction/quick-start-guide.md - - MCP Server: cloud/introduction/quick-start-guide-mcp.md + - Quick start guide: + - API proxy: cloud/introduction/quick-start-guide.md + - MCP server: cloud/introduction/quick-start-guide-mcp.md - Concepts: # - Resource Hierarchy: resource-hierarchy.md - Organization: cloud/bijira-concepts/organization.md - Project: cloud/bijira-concepts/project.md # - Deployment Tracks: cloud/bijira-concepts/deployment-tracks.md - - Data Planes: cloud/bijira-concepts/data-planes.md - - Create API Proxy: + - Data planes: cloud/bijira-concepts/data-planes.md + - Create API proxy: - Overview: cloud/create-api-proxy/overview.md - - My APIs (Ingress): + - My APIs (ingress): - REST APIs: - Create with GenAI: cloud/create-api-proxy/my-apis/http/create-with-genai.md - - Import API Contract: cloud/create-api-proxy/my-apis/http/import-api-contract.md - - Import API Contract from GitHub: cloud/create-api-proxy/my-apis/http/import-api-from-github.md - - Start with Endpoint: cloud/create-api-proxy/my-apis/http/start-with-endpoint.md - - Start from Scratch: cloud/create-api-proxy/my-apis/http/start-from-scratch.md + - Import API contract: cloud/create-api-proxy/my-apis/http/import-api-contract.md + - Import API contract from GitHub: cloud/create-api-proxy/my-apis/http/import-api-from-github.md + - Start with endpoint: cloud/create-api-proxy/my-apis/http/start-with-endpoint.md + - Start from scratch: cloud/create-api-proxy/my-apis/http/start-from-scratch.md - WebSocket APIs: - Create with GenAI: cloud/create-api-proxy/my-apis/websocket/create-with-genai.md - - Import API Contract: cloud/create-api-proxy/my-apis/websocket/import-api-contract.md - - Start with Endpoint: cloud/create-api-proxy/my-apis/websocket/start-with-endpoint.md - - Start from Scratch: cloud/create-api-proxy/my-apis/websocket/start-from-scratch.md + - Import API contract: cloud/create-api-proxy/my-apis/websocket/import-api-contract.md + - Start with endpoint: cloud/create-api-proxy/my-apis/websocket/start-with-endpoint.md + - Start from scratch: cloud/create-api-proxy/my-apis/websocket/start-from-scratch.md - Limitations: cloud/create-api-proxy/my-apis/websocket/quotas-and-limitations.md - GraphQL APIs: - - Import API Contract: cloud/create-api-proxy/my-apis/graphql/import-api-contract.md - - Start with Endpoint: cloud/create-api-proxy/my-apis/graphql/start-with-endpoint.md - - Third Party APIs (Egress): + - Import API contract: cloud/create-api-proxy/my-apis/graphql/import-api-contract.md + - Start with endpoint: cloud/create-api-proxy/my-apis/graphql/start-with-endpoint.md + - Third party APIs (egress): - AI APIs: - Overview: cloud/create-api-proxy/third-party-apis/ai-apis.md - Providers: @@ -112,120 +112,120 @@ nav: - AWS Bedrock: cloud/create-api-proxy/third-party-apis/awsbedrock.md - Anthropic: cloud/create-api-proxy/third-party-apis/claude.md - Policies: - - Token-Based Rate Limit: cloud/create-api-proxy/third-party-apis/token-ratelimit.md + - Token-based rate limit: cloud/create-api-proxy/third-party-apis/token-ratelimit.md - Guardrails: - Overview: cloud/create-api-proxy/third-party-apis/guardrails.md # - Basic Guardrails: - - Regex Guardrail: cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/regex-guardrail.md - - Word Count Guardrail: cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/word-count-guardrail.md - - Sentence Count Guardrail: cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/sentence-count-guardrail.md - - Content Length Guardrail: cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/content-length-guardrail.md - - URL Guardrail: cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/url-guardrail.md - - Regex PII Masking: cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/regex-pii-masking.md + - Regex guardrail: cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/regex-guardrail.md + - Word count guardrail: cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/word-count-guardrail.md + - Sentence count guardrail: cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/sentence-count-guardrail.md + - Content length guardrail: cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/content-length-guardrail.md + - URL guardrail: cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/url-guardrail.md + - Regex PII masking: cloud/create-api-proxy/third-party-apis/guardrails/basic-guardrails/regex-pii-masking.md # - Advanced Guardrails: - - PII Masking: cloud/create-api-proxy/third-party-apis/guardrails/advanced-guardrails/pii-masking.md + - PII masking: cloud/create-api-proxy/third-party-apis/guardrails/advanced-guardrails/pii-masking.md # - Third Party Guardrail Integrations: - - Azure Content Safety Content Moderation: cloud/create-api-proxy/third-party-apis/guardrails/third-party-guardrail-integrations/azure-content-safety-content-moderation.md - - AWS Bedrock Guardrail: cloud/create-api-proxy/third-party-apis/guardrails/third-party-guardrail-integrations/aws-bedrock-guardrail.md - - Semantic Cache: cloud/create-api-proxy/third-party-apis/semantic-cache.md - - Get from Marketplace: cloud/create-api-proxy/third-party-apis/get-from-marketplace.md - - Import API Contract: cloud/create-api-proxy/third-party-apis/import-api-contract.md - - Develop API Proxy: - - Authentication and Authorization: - - Secure API Access with Asgardeo: cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-asgardeo.md - - Secure API Access with API Platform STS: cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-bijira-sts.md - - Secure API Access with Azure AD: cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-azure-ad.md - - Secure API Access with an External Key Manager: cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-external-idp.md - - Secure Communication Between the API Platform Gateway and Your Backend with OAuth2: cloud/develop-api-proxy/authentication-and-authorization/secure-communication-between-bijira-gateway-and-backend-with-oauth2.md - - Secure Communication Between the API Platform Gateway and Your Backend with Mutual TLS: cloud/develop-api-proxy/authentication-and-authorization/secure-communication-between-the-bijira-gateway-and-your-backend-with-mutual-tls.md + - Azure Content Safety content moderation: cloud/create-api-proxy/third-party-apis/guardrails/third-party-guardrail-integrations/azure-content-safety-content-moderation.md + - AWS Bedrock guardrail: cloud/create-api-proxy/third-party-apis/guardrails/third-party-guardrail-integrations/aws-bedrock-guardrail.md + - Semantic cache: cloud/create-api-proxy/third-party-apis/semantic-cache.md + - Get from marketplace: cloud/create-api-proxy/third-party-apis/get-from-marketplace.md + - Import API contract: cloud/create-api-proxy/third-party-apis/import-api-contract.md + - Develop API proxy: + - Authentication and authorization: + - Secure API access with Asgardeo: cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-asgardeo.md + - Secure API access with API Platform STS: cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-bijira-sts.md + - Secure API access with Azure AD: cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-azure-ad.md + - Secure API access with an external key manager: cloud/develop-api-proxy/authentication-and-authorization/secure-api-access-with-external-idp.md + - Secure communication between the API Platform gateway and your backend with OAuth2: cloud/develop-api-proxy/authentication-and-authorization/secure-communication-between-bijira-gateway-and-backend-with-oauth2.md + - Secure communication between the API Platform gateway and your backend with mutual TLS: cloud/develop-api-proxy/authentication-and-authorization/secure-communication-between-the-bijira-gateway-and-your-backend-with-mutual-tls.md - Policy: - Overview: cloud/develop-api-proxy/policy/overview.md - Policies: cloud/develop-api-proxy/policy/policies.md - - Attach and Manage Policies: cloud/develop-api-proxy/policy/attach-and-manage-policies.md + - Attach and manage policies: cloud/develop-api-proxy/policy/attach-and-manage-policies.md # - Apply Advanced Settings on Mediation Policies: cloud/develop-api-proxy/policy/apply-advanced-settings-on-mediation-policies.md - Documents: cloud/develop-api-proxy/documents.md - - Make an API AI-Ready: cloud/develop-api-proxy/make-api-ai-ready.md + - Make an API AI-ready: cloud/develop-api-proxy/make-api-ai-ready.md - Lifecycle: cloud/develop-api-proxy/lifecycle-management.md - - Subscription Plans: cloud/develop-api-proxy/subscription-plans.md - - Test API Proxy: - - OpenAPI Console: cloud/test-api-proxy/openapi-console.md - - WebSocket Console: cloud/test-api-proxy/ws-test-console.md - - GraphQL Console: cloud/test-api-proxy/graphql-console.md + - Subscription plans: cloud/develop-api-proxy/subscription-plans.md + - Test API proxy: + - OpenAPI console: cloud/test-api-proxy/openapi-console.md + - WebSocket console: cloud/test-api-proxy/ws-test-console.md + - GraphQL console: cloud/test-api-proxy/graphql-console.md - cURL: cloud/test-api-proxy/curl.md - - API Chat: cloud/test-api-proxy/api-chat.md - - MCP Servers: + - API chat: cloud/test-api-proxy/api-chat.md + - MCP servers: - Overview: cloud/mcp-servers/get-started-with-mcp.md - - Design MCP Servers: cloud/mcp-servers/design-mcp-servers.md - - Proxy Remote MCP Servers: cloud/mcp-servers/proxy-remote-servers.md + - Design MCP servers: cloud/mcp-servers/design-mcp-servers.md + - Proxy remote MCP servers: cloud/mcp-servers/proxy-remote-servers.md - Customize Developer Portal as an MCP Hub: cloud/mcp-servers/devportal-mcp-hub.md - - API Governance: - - API Governance Overview: cloud/governance/overview.md - - Govern API Proxy: cloud/governance/govern-api-proxy.md + - API governance: + - API governance overview: cloud/governance/overview.md + - Govern API proxy: cloud/governance/govern-api-proxy.md - AI Gateway: - Overview: cloud/ai-gateway/overview.md - LLM: - - Quick Start Guide: cloud/ai-gateway/llm/quick-start-guide.md - - LLM Provider Templates: cloud/ai-gateway/llm/llm-templates.md + - Quick start guide: cloud/ai-gateway/llm/quick-start-guide.md + - LLM provider templates: cloud/ai-gateway/llm/llm-templates.md - Guardrails: - - AWS Bedrock Guardrail: cloud/ai-gateway/llm/guardrails/aws-bedrock-guardrail.md + - AWS Bedrock guardrail: cloud/ai-gateway/llm/guardrails/aws-bedrock-guardrail.md - Azure Content Safety: cloud/ai-gateway/llm/guardrails/azure-content-safety.md - - Content Length Guardrail: cloud/ai-gateway/llm/guardrails/content-length.md - - JSON Schema Guardrail: cloud/ai-gateway/llm/guardrails/json-schema.md - - PII Masking Regex Guardrail: cloud/ai-gateway/llm/guardrails/pii-masking-regex.md - - Regex Guardrail: cloud/ai-gateway/llm/guardrails/regex.md - - Semantic Prompt Guardrail: cloud/ai-gateway/llm/guardrails/semantic-prompt-guard.md - - Semantic Tool Filtering: cloud/ai-gateway/llm/guardrails/semantic-tool-filtering.md - - Sentence Count Guardrail: cloud/ai-gateway/llm/guardrails/sentence-count.md - - URL Guardrail: cloud/ai-gateway/llm/guardrails/url.md - - Word Count Guardrail: cloud/ai-gateway/llm/guardrails/word-count.md - - Load Balancing: - - Model Round Robin: cloud/ai-gateway/llm/load-balancing/model-round-robin.md - - Model Weighted Round Robin: cloud/ai-gateway/llm/load-balancing/model-weighted-round-robin.md - - Prompt Management: - - Prompt Decorator: cloud/ai-gateway/llm/prompt-management/prompt-decorator.md - - Prompt Template: cloud/ai-gateway/llm/prompt-management/prompt-template.md - - Semantic Caching: cloud/ai-gateway/llm/semantic-caching.md - - AI Tools: + - Content length guardrail: cloud/ai-gateway/llm/guardrails/content-length.md + - JSON schema guardrail: cloud/ai-gateway/llm/guardrails/json-schema.md + - PII masking regex guardrail: cloud/ai-gateway/llm/guardrails/pii-masking-regex.md + - Regex guardrail: cloud/ai-gateway/llm/guardrails/regex.md + - Semantic prompt guardrail: cloud/ai-gateway/llm/guardrails/semantic-prompt-guard.md + - Semantic tool filtering: cloud/ai-gateway/llm/guardrails/semantic-tool-filtering.md + - Sentence count guardrail: cloud/ai-gateway/llm/guardrails/sentence-count.md + - URL guardrail: cloud/ai-gateway/llm/guardrails/url.md + - Word count guardrail: cloud/ai-gateway/llm/guardrails/word-count.md + - Load balancing: + - Model round robin: cloud/ai-gateway/llm/load-balancing/model-round-robin.md + - Model weighted round robin: cloud/ai-gateway/llm/load-balancing/model-weighted-round-robin.md + - Prompt management: + - Prompt decorator: cloud/ai-gateway/llm/prompt-management/prompt-decorator.md + - Prompt template: cloud/ai-gateway/llm/prompt-management/prompt-template.md + - Semantic caching: cloud/ai-gateway/llm/semantic-caching.md + - AI tools: - Claude Code configuration with AI Gateway: cloud/ai-gateway/llm/ai-tools/claude-code-configuration-with-ai-gateway.md - Google Gemini CLI configuration with AI Gateway: cloud/ai-gateway/llm/ai-tools/gemini-cli-configuration-with-ai-gateway.md - OpenAI Codex CLI configuration with AI Gateway: cloud/ai-gateway/llm/ai-tools/codex-configuration-with-ai-gateway.md - MCP: - - Quick Start Guide: cloud/ai-gateway/mcp/quick-start-guide.md + - Quick start guide: cloud/ai-gateway/mcp/quick-start-guide.md - Policies: - - MCP Access Control List: cloud/ai-gateway/mcp/policies/mcp-acl-list.md - - MCP Authentication: cloud/ai-gateway/mcp/policies/mcp-authentication.md - - MCP Authorization: cloud/ai-gateway/mcp/policies/mcp-authorization.md - - MCP Rewrite: cloud/ai-gateway/mcp/policies/mcp-rewrite.md + - MCP access control list: cloud/ai-gateway/mcp/policies/mcp-acl-list.md + - MCP authentication: cloud/ai-gateway/mcp/policies/mcp-authentication.md + - MCP authorization: cloud/ai-gateway/mcp/policies/mcp-authorization.md + - MCP rewrite: cloud/ai-gateway/mcp/policies/mcp-rewrite.md - Observability: - Logging: cloud/ai-gateway/observability/logging.md - Tracing: cloud/ai-gateway/observability/tracing.md - Analytics: - - Moesif Analytics: cloud/ai-gateway/analytics/moesif-analytics.md - - Analytics Header Filter: cloud/ai-gateway/analytics/analytics-header-filter.md + - Moesif analytics: cloud/ai-gateway/analytics/moesif-analytics.md + - Analytics header filter: cloud/ai-gateway/analytics/analytics-header-filter.md - AI Workspace: - Overview: cloud/ai-workspace/overview.md - - Getting Started: cloud/ai-workspace/getting-started.md - - AI Gateways: - - Setting Up: cloud/ai-workspace/ai-gateways/setting-up.md - - LLM Providers: + - Getting started: cloud/ai-workspace/getting-started.md + - AI gateways: + - Setting up: cloud/ai-workspace/ai-gateways/setting-up.md + - LLM providers: - Overview: cloud/ai-workspace/llm-providers/overview.md - - Configure Provider: cloud/ai-workspace/llm-providers/configure-provider.md - - Manage Provider: cloud/ai-workspace/llm-providers/manage-provider.md - - App LLM Proxies: + - Configure provider: cloud/ai-workspace/llm-providers/configure-provider.md + - Manage provider: cloud/ai-workspace/llm-providers/manage-provider.md + - App LLM proxies: - Overview: cloud/ai-workspace/llm-proxies/overview.md - - Configure App LLM Proxy: cloud/ai-workspace/llm-proxies/configure-proxy.md - - Manage App LLM Proxy: cloud/ai-workspace/llm-proxies/manage-proxy.md - - MCP Proxies: + - Configure app LLM proxy: cloud/ai-workspace/llm-proxies/configure-proxy.md + - Manage app LLM proxy: cloud/ai-workspace/llm-proxies/manage-proxy.md + - MCP proxies: - Overview: cloud/ai-workspace/mcp-proxies/overview.md - - Configure Proxy: cloud/ai-workspace/mcp-proxies/configure-proxy.md - - Apply Policies: cloud/ai-workspace/mcp-proxies/apply-policies.md + - Configure proxy: cloud/ai-workspace/mcp-proxies/configure-proxy.md + - Apply policies: cloud/ai-workspace/mcp-proxies/apply-policies.md - MCP Registry: - What is an MCP Registry?: cloud/mcp-servers/mcp-registry.md - - Publish MCP Proxies: cloud/mcp-servers/publish-mcp-proxies.md + - Publish MCP proxies: cloud/mcp-servers/publish-mcp-proxies.md - Browse the MCP Hub: cloud/mcp-servers/browse-mcp-hub.md - Use the MCP Registry API: cloud/mcp-servers/mcp-registry-api.md - - GenAI Applications: cloud/ai-workspace/genai-applications.md - - Configure Inbound Auth: cloud/ai-workspace/configure-inbound-auth.md + - GenAI applications: cloud/ai-workspace/genai-applications.md + - Configure inbound auth: cloud/ai-workspace/configure-inbound-auth.md - Invoke via SDKs: cloud/ai-workspace/using-sdks.md # - Insights: cloud/ai-workspace/insights.md - Policies: @@ -233,140 +233,140 @@ nav: - Guardrails: - Overview: cloud/ai-workspace/policies/guardrails/overview.md # - Semantic Prompt Guard: cloud/ai-workspace/policies/guardrails/semantic-prompt-guard.md - - PII Masking Regex: cloud/ai-workspace/policies/guardrails/regex-pii-masking.md + - PII masking regex: cloud/ai-workspace/policies/guardrails/regex-pii-masking.md - Azure Content Safety: cloud/ai-workspace/policies/guardrails/azure-content-safety.md - - Word Count: cloud/ai-workspace/policies/guardrails/word-count-guardrail.md - - Sentence Count: cloud/ai-workspace/policies/guardrails/sentence-count-guardrail.md - - Rate Limit: - - LLM Cost: cloud/ai-workspace/policies/rate-limit/llm-cost.md - - Token-Based Rate Limit: cloud/ai-workspace/policies/rate-limit/token-based-rate-limit.md - - LLM Cost-Based Rate Limit: cloud/ai-workspace/policies/rate-limit/llm-cost-based-rate-limit.md - - Other Policies: + - Word count: cloud/ai-workspace/policies/guardrails/word-count-guardrail.md + - Sentence count: cloud/ai-workspace/policies/guardrails/sentence-count-guardrail.md + - Rate limit: + - LLM cost: cloud/ai-workspace/policies/rate-limit/llm-cost.md + - Token-based rate limit: cloud/ai-workspace/policies/rate-limit/token-based-rate-limit.md + - LLM Cost-based rate limit: cloud/ai-workspace/policies/rate-limit/llm-cost-based-rate-limit.md + - Other policies: # - Token-Based Rate Limit: cloud/ai-workspace/policies/other-policies/token-based-rate-limit.md # - Rate Limit - Basic: cloud/ai-workspace/policies/other-policies/basic-rate-limit.md - - Model Round Robin: cloud/ai-workspace/policies/other-policies/model-round-robin.md - - Prompt Decorator: cloud/ai-workspace/policies/other-policies/prompt-decorator.md - - Prompt Template: cloud/ai-workspace/policies/other-policies/prompt-template.md - - Semantic Cache: cloud/ai-workspace/policies/other-policies/semantic-cache.md - - Writing an AI Policy: cloud/ai-workspace/policies/writing-an-ai-policy.md + - Model round robin: cloud/ai-workspace/policies/other-policies/model-round-robin.md + - Prompt decorator: cloud/ai-workspace/policies/other-policies/prompt-decorator.md + - Prompt template: cloud/ai-workspace/policies/other-policies/prompt-template.md + - Semantic cache: cloud/ai-workspace/policies/other-policies/semantic-cache.md + - Writing an AI policy: cloud/ai-workspace/policies/writing-an-ai-policy.md - Event Gateway: - Overview: cloud/event-gateway/overview.md - - Getting Started: cloud/event-gateway/getting-started.md - - Setting Up: cloud/event-gateway/setting-up.md + - Getting started: cloud/event-gateway/getting-started.md + - Setting up: cloud/event-gateway/setting-up.md - Publish APIs: - Overview: cloud/event-gateway/publish-apis/overview.md - - Subscription Based APIs: cloud/event-gateway/publish-apis/subscription-based-apis.md - - Subscription Less APIs: cloud/event-gateway/publish-apis/subscription-less-apis.md - - Lifecycle Management: cloud/event-gateway/publish-apis/lifecycle-management.md + - Subscription based APIs: cloud/event-gateway/publish-apis/subscription-based-apis.md + - Subscription less APIs: cloud/event-gateway/publish-apis/subscription-less-apis.md + - Lifecycle management: cloud/event-gateway/publish-apis/lifecycle-management.md - Troubleshooting: cloud/event-gateway/troubleshooting.md - API Gateway: # - Overview: cloud/api-platform-gateway/overview.md # - API Platform Cloud Gateway: cloud/api-platform-gateway/cloud-gateway.md - - Self-Hosted Gateway: + - Self-hosted gateway: - Architecture: cloud/api-platform-gateway/architecture.md - - Getting Started: cloud/api-platform-gateway/getting-started.md - - Setting Up: cloud/api-platform-gateway/setting-up.md - - Adding and Managing Policies: cloud/api-platform-gateway/manage-policies.md - - Custom Policies: - - Writing a Custom Policy: cloud/api-platform-gateway/writing-a-custom-policy.md - - Building the Gateway with Custom Policies: cloud/api-platform-gateway/build-gateway-with-custom-policies.md - - Apply Custom Policies to APIs: cloud/api-platform-gateway/apply-custom-policies-to-apis.md + - Getting started: cloud/api-platform-gateway/getting-started.md + - Setting up: cloud/api-platform-gateway/setting-up.md + - Adding and managing policies: cloud/api-platform-gateway/manage-policies.md + - Custom policies: + - Writing a custom policy: cloud/api-platform-gateway/writing-a-custom-policy.md + - Building the gateway with custom policies: cloud/api-platform-gateway/build-gateway-with-custom-policies.md + - Apply custom policies to APIs: cloud/api-platform-gateway/apply-custom-policies-to-apis.md - Publish APIs: - Overview: cloud/api-platform-gateway/publish-apis/overview.md - - Subscription Based APIs: cloud/api-platform-gateway/publish-apis/subscription-based-apis.md - - Subscription Less APIs: cloud/api-platform-gateway/publish-apis/subscription-less-apis.md - - Lifecycle Management: cloud/api-platform-gateway/publish-apis/lifecycle-management.md - - High Availability: cloud/api-platform-gateway/high-availability.md + - Subscription based APIs: cloud/api-platform-gateway/publish-apis/subscription-based-apis.md + - Subscription less APIs: cloud/api-platform-gateway/publish-apis/subscription-less-apis.md + - Lifecycle management: cloud/api-platform-gateway/publish-apis/lifecycle-management.md + - High availability: cloud/api-platform-gateway/high-availability.md # - Analytics: cloud/api-platform-gateway/analytics.md # - Troubleshooting: cloud/api-platform-gateway/troubleshooting.md - - Third-Party Gateways: + - Third-party gateways: - Overview: cloud/federation/overview.md - Discover APIs from AWS API Gateway: cloud/federation/api-discovery-aws.md - - Monitor and Insights: + - Monitor and insights: - Logs: - Overview: cloud/monitoring-and-insights/logs/overview.md - - Runtime Logs: cloud/monitoring-and-insights/logs/runtime-logs.md - - Audit Logs: cloud/monitoring-and-insights/logs/audit-logs.md + - Runtime logs: cloud/monitoring-and-insights/logs/runtime-logs.md + - Audit logs: cloud/monitoring-and-insights/logs/audit-logs.md - Insights: cloud/monitoring-and-insights/insights.md - - Compliance Dashboard: cloud/monitoring-and-insights/compliance.md + - Compliance dashboard: cloud/monitoring-and-insights/compliance.md - Integrate API Platform with Moesif: cloud/monitoring-and-insights/integrate-bijira-with-moesif.md - - API Platform Status Page: cloud/monitoring-and-insights/status-page.md - - API Monetization: + - API Platform status page: cloud/monitoring-and-insights/status-page.md + - API monetization: - Overview: cloud/api-monetization/overview.md - Monetizing APIs: - - Getting Started: cloud/api-monetization/getting-started.md - - Manage Paid Subscription Plans: cloud/api-monetization/manage-paid-subscription-plans.md - - Consume Monetized APIs: - - Subscribe to a Paid Plan: cloud/api-monetization/subscribe-to-paid-plan.md - - View Billing and Usage: cloud/api-monetization/view-billing-and-usage.md + - Getting started: cloud/api-monetization/getting-started.md + - Manage paid subscription plans: cloud/api-monetization/manage-paid-subscription-plans.md + - Consume monetized APIs: + - Subscribe to a paid plan: cloud/api-monetization/subscribe-to-paid-plan.md + - View billing and usage: cloud/api-monetization/view-billing-and-usage.md - Administer: - - Create API Subscription Plans: cloud/administer/settings/create-api-subscription-plans.md - - Configure a Custom Domain for Your Organization: cloud/administer/settings/configure-a-custom-domain-for-your-organization.md - - Manage Environments: cloud/administer/manage-environments/manage-environments.md + - Create API subscription plans: cloud/administer/settings/create-api-subscription-plans.md + - Configure a custom domain for your organization: cloud/administer/settings/configure-a-custom-domain-for-your-organization.md + - Manage environments: cloud/administer/manage-environments/manage-environments.md - Manage CD pipelines: cloud/administer/manage-cd-pipelines/manage-cd-pipelines.md - - Configure External Key Manager: - - Configure Asgardeo as an External Key Manager: cloud/administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp.md - - Configure Azure as an External Key Manager: cloud/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md - - Configure Custom External Key Manager: cloud/administer/configure-an-external-idp/configure-custom-external-idp.md - - Configure Enterprise Login: cloud/administer/configure-enterprise-login/configure-enterprise-login.md - - Configure VPNs on API Platform Cloud Data Plane: cloud/administer/configure-vpns/configure-vpns.md + - Configure external key manager: + - Configure Asgardeo as an external key manager: cloud/administer/configure-an-external-idp/configure-asgardeo-as-an-external-idp.md + - Configure Azure as an external key manager: cloud/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md + - Configure custom external key manager: cloud/administer/configure-an-external-idp/configure-custom-external-idp.md + - Configure enterprise login: cloud/administer/configure-enterprise-login/configure-enterprise-login.md + - Configure VPNs on API Platform Cloud data plane: cloud/administer/configure-vpns/configure-vpns.md - Workflows: - - Configure Workflow Approvals: cloud/workflows/configure-workflow-approvals.md - - Submit Workflow Approval Requests: cloud/workflows/submit-workflow-requests.md - - Review Workflow Approval Requests: cloud/workflows/review-workflows-requests.md + - Configure workflow approvals: cloud/workflows/configure-workflow-approvals.md + - Submit workflow approval requests: cloud/workflows/submit-workflow-requests.md + - Review workflow approval requests: cloud/workflows/review-workflows-requests.md - Tutorials: - - Expose a Service as a Managed API: cloud/tutorials/expose-a-service-as-a-managed-api.md + - Expose a service as a managed API: cloud/tutorials/expose-a-service-as-a-managed-api.md - Secure an API with RBAC: cloud/tutorials/secure-an-api-with-role-based-access-control.md - - API Platform Samples: - - Samples Overview: cloud/samples/samples-overview.md + - API Platform samples: + - Samples overview: cloud/samples/samples-overview.md - Developer Portal: - Theming Developer Portal: - Theming with AI: cloud/devportal/theming-devportal-with-ai.md - - Theming Manually: - - Theme in Organizational Level: cloud/devportal/theming-devportal-org-level.md - - Theme in API Level: cloud/devportal/theming-devportal-api-level.md - - Devportal Mode: cloud/devportal/developer-portal-mode.md - - AI Agent Discovery: cloud/devportal/discover-apis/ai-agent-discovery.md + - Theming manually: + - Theme in organizational level: cloud/devportal/theming-devportal-org-level.md + - Theme in API level: cloud/devportal/theming-devportal-api-level.md + - Devportal mode: cloud/devportal/developer-portal-mode.md + - AI agent discovery: cloud/devportal/discover-apis/ai-agent-discovery.md - Discover APIs: - Search APIs: cloud/devportal/discover-apis/api-search.md - Documentations: cloud/devportal/discover-apis/api-documentations.md - - API Workflows: - - Consuming API Workflows: cloud/devportal/api-workflows/consuming-api-workflows.md + - API workflows: + - Consuming API workflows: cloud/devportal/api-workflows/consuming-api-workflows.md - Consume an API: - - Consume an API Secured with OAuth2: cloud/devportal/consuming-services/consume-an-api-secured-with-oauth2.md - - Consume an API Secured with API Key: cloud/devportal/consuming-services/consume-an-api-secured-with-api-key.md - - Manage Applications: - - Create an Application: cloud/devportal/manage-applications/create-an-application.md - - Manage Subscriptions: + - Consume an API secured with OAuth2: cloud/devportal/consuming-services/consume-an-api-secured-with-oauth2.md + - Consume an API secured with API key: cloud/devportal/consuming-services/consume-an-api-secured-with-api-key.md + - Manage applications: + - Create an application: cloud/devportal/manage-applications/create-an-application.md + - Manage subscriptions: - Subscribe to an API: cloud/devportal/manage-subscriptions/subscribe-to-an-api.md - - SDK Generation: - - AI Assisted SDK Generation: cloud/devportal/sdk-generation/ai-assisted-sdk-generation.md - - Admin Settings: - - LLM Instructions: cloud/devportal/admin-settings/llm-instructions.md - - Managing API Workflows: cloud/devportal/admin-settings/managing-api-workflows.md + - SDK generation: + - AI assisted SDK generation: cloud/devportal/sdk-generation/ai-assisted-sdk-generation.md + - Admin settings: + - LLM instructions: cloud/devportal/admin-settings/llm-instructions.md + - Managing API workflows: cloud/devportal/admin-settings/managing-api-workflows.md - API Manager: - Overview: api-manager/overview.md - Documentation: https://apim.docs.wso2.com/en/latest/ - API Gateway: - Overview: api-gateway/overview.md - Setup: - - Storage & Backends: api-gateway/setup/storage-and-backends.md - - Artifact Templating: api-gateway/setup/artifact-templating.md - - Upstream Timeouts: api-gateway/setup/upstream-timeouts.md - - Quick Start Guide: api-gateway/quick-start-guide.md + - Storage & backends: api-gateway/setup/storage-and-backends.md + - Artifact templating: api-gateway/setup/artifact-templating.md + - Upstream timeouts: api-gateway/setup/upstream-timeouts.md + - Quick start guide: api-gateway/quick-start-guide.md - Policies: - Overview: api-gateway/policies/overview.md - - Custom Policies: - - Writing a Custom Policy: api-gateway/policies/custom-policies/writing-a-custom-policy.md - - Building Gateway with Custom Policies: api-gateway/policies/custom-policies/building-gateway-with-custom-policies.md + - Custom policies: + - Writing a custom policy: api-gateway/policies/custom-policies/writing-a-custom-policy.md + - Building gateway with custom policies: api-gateway/policies/custom-policies/building-gateway-with-custom-policies.md - Deployment: - - Deployment Modes: - - Immutable Gateway: api-gateway/deployment/deployment-modes/immutable-gateway.md + - Deployment modes: + - Immutable gateway: api-gateway/deployment/deployment-modes/immutable-gateway.md - Kubernetes: - Overview: api-gateway/deployment/deployment-modes/kubernetes/overview.md - - Standalone Mode: api-gateway/deployment/deployment-modes/kubernetes/kubernetes-standalone.md - - Kubernetes Operator Mode: api-gateway/deployment/deployment-modes/kubernetes/gateway-operator.md + - Standalone mode: api-gateway/deployment/deployment-modes/kubernetes/kubernetes-standalone.md + - Kubernetes operator mode: api-gateway/deployment/deployment-modes/kubernetes/gateway-operator.md - Management CRDs: api-gateway/deployment/deployment-modes/kubernetes/gateway-operator-management-crds.md - High-Availability Production Deployment: - Overview: api-gateway/deployment/high-availability-production-deployment.md @@ -376,86 +376,86 @@ nav: - Deploy & Verify: api-gateway/deployment/production-deployment/deploy-and-verify.md - Control Plane Connection: api-gateway/deployment/production-deployment/control-plane-connection.md - Deploying APIs: - - Bottom-Up Deployment: api-gateway/deployment/deploying-apis/bottom-up-api-deployment.md + - Bottom-up deployment: api-gateway/deployment/deploying-apis/bottom-up-api-deployment.md - Observability: - Logging: api-gateway/observability/logging.md - Tracing: - Overview: api-gateway/observability/tracing/overview.md - - Enabling and Disabling Tracing: api-gateway/observability/tracing/enabling-tracing.md - - Viewing Traces in Jaeger: api-gateway/observability/tracing/viewing-traces-in-jaeger.md - - Tracing Configuration: api-gateway/observability/tracing/configuration.md - - Alternative Tracing Backends: api-gateway/observability/tracing/alternative-backends.md - - Best Practices and Troubleshooting: api-gateway/observability/tracing/best-practices-and-troubleshooting.md + - Enabling and disabling tracing: api-gateway/observability/tracing/enabling-tracing.md + - Viewing traces in Jaeger: api-gateway/observability/tracing/viewing-traces-in-jaeger.md + - Tracing configuration: api-gateway/observability/tracing/configuration.md + - Alternative tracing backends: api-gateway/observability/tracing/alternative-backends.md + - Best practices and troubleshooting: api-gateway/observability/tracing/best-practices-and-troubleshooting.md - Metrics: - Overview: api-gateway/observability/metrics/overview.md - - Enabling and Disabling Metrics: api-gateway/observability/metrics/enabling-metrics.md - - Viewing Metrics in Grafana: api-gateway/observability/metrics/viewing-metrics-in-grafana.md - - Prometheus Queries: api-gateway/observability/metrics/prometheus-queries.md - - Configuration Options: api-gateway/observability/metrics/configuration.md - - Alternative Metrics Backends: api-gateway/observability/metrics/alternative-backends.md - - Metric Reference: api-gateway/observability/metrics/metric-reference.md - - Best Practices and Troubleshooting: api-gateway/observability/metrics/best-practices-and-troubleshooting.md + - Enabling and disabling metrics: api-gateway/observability/metrics/enabling-metrics.md + - Viewing metrics in Grafana: api-gateway/observability/metrics/viewing-metrics-in-grafana.md + - Prometheus queries: api-gateway/observability/metrics/prometheus-queries.md + - Configuration options: api-gateway/observability/metrics/configuration.md + - Alternative metrics backends: api-gateway/observability/metrics/alternative-backends.md + - Metric reference: api-gateway/observability/metrics/metric-reference.md + - Best practices and troubleshooting: api-gateway/observability/metrics/best-practices-and-troubleshooting.md - Analytics: - - Analytics Header Filter: api-gateway/analytics/analytics-header-filter.md - - Moesif Analytics: api-gateway/analytics/moesif-analytics.md + - Analytics header filter: api-gateway/analytics/analytics-header-filter.md + - Moesif analytics: api-gateway/analytics/moesif-analytics.md - Management API: - Overview: api-gateway/gateway-controller-management-api/overview.md - Authentication: api-gateway/gateway-controller-management-api/authentication.md - - Rest API Management: api-gateway/gateway-controller-management-api/rest-api-management.md - - MCP Proxy Management: api-gateway/gateway-controller-management-api/mcp-proxy-management.md - - Certificate Management: api-gateway/gateway-controller-management-api/certificate-management.md - - LLM Provider Template Management: api-gateway/gateway-controller-management-api/llm-provider-template-management.md - - LLM Provider Management: api-gateway/gateway-controller-management-api/llm-provider-management.md - - LLM Proxy Management: api-gateway/gateway-controller-management-api/llm-proxy-management.md - - Secrets Management: api-gateway/gateway-controller-management-api/secrets-management.md - - WebSub API Management: api-gateway/gateway-controller-management-api/websub-api-management.md - - WebBroker API Management: api-gateway/gateway-controller-management-api/webbroker-api-management.md + - Rest API management: api-gateway/gateway-controller-management-api/rest-api-management.md + - MCP proxy management: api-gateway/gateway-controller-management-api/mcp-proxy-management.md + - Certificate management: api-gateway/gateway-controller-management-api/certificate-management.md + - LLM provider template management: api-gateway/gateway-controller-management-api/llm-provider-template-management.md + - LLM provider management: api-gateway/gateway-controller-management-api/llm-provider-management.md + - LLM proxy management: api-gateway/gateway-controller-management-api/llm-proxy-management.md + - Secrets management: api-gateway/gateway-controller-management-api/secrets-management.md + - WebSub API management: api-gateway/gateway-controller-management-api/websub-api-management.md + - WebBroker API management: api-gateway/gateway-controller-management-api/webbroker-api-management.md - Schemas: api-gateway/gateway-controller-management-api/schemas.md - AI Gateway: - Overview: ai-gateway/overview.md - - LLM Proxy: - - Quick Start Guide: ai-gateway/llm-proxy/quick-start-guide.md - - LLM Provider Templates: ai-gateway/llm-proxy/llm-templates.md + - LLM proxy: + - Quick start guide: ai-gateway/llm-proxy/quick-start-guide.md + - LLM provider templates: ai-gateway/llm-proxy/llm-templates.md - Guardrails: - - AWS Bedrock Guardrail: ai-gateway/llm-proxy/guardrails/aws-bedrock-guardrail.md + - AWS Bedrock guardrail: ai-gateway/llm-proxy/guardrails/aws-bedrock-guardrail.md - Azure Content Safety: ai-gateway/llm-proxy/guardrails/azure-content-safety.md - - Content Length Guardrail: ai-gateway/llm-proxy/guardrails/content-length.md - - JSON Schema Guardrail: ai-gateway/llm-proxy/guardrails/json-schema.md - - PII Masking Regex Guardrail: ai-gateway/llm-proxy/guardrails/pii-masking-regex.md - - Regex Guardrail: ai-gateway/llm-proxy/guardrails/regex.md - - Semantic Prompt Guardrail: ai-gateway/llm-proxy/guardrails/semantic-prompt-guard.md - - Sentence Count Guardrail: ai-gateway/llm-proxy/guardrails/sentence-count.md - - URL Guardrail: ai-gateway/llm-proxy/guardrails/url.md - - Word Count Guardrail: ai-gateway/llm-proxy/guardrails/word-count.md - - Load Balancing: - - Model Round Robin: ai-gateway/llm-proxy/load-balancing/model-round-robin.md - - Model Weighted Round Robin: ai-gateway/llm-proxy/load-balancing/model-weighted-round-robin.md - - Prompt Management: - - Prompt Decorator: ai-gateway/llm-proxy/prompt-management/prompt-decorator.md - - Prompt Template: ai-gateway/llm-proxy/prompt-management/prompt-template.md - - Semantic Caching: ai-gateway/llm-proxy/semantic-caching.md - - MCP Proxy: - - Quick Start Guide: ai-gateway/mcp-proxy/quick-start-guide.md + - Content length guardrail: ai-gateway/llm-proxy/guardrails/content-length.md + - JSON schema guardrail: ai-gateway/llm-proxy/guardrails/json-schema.md + - PII masking regex guardrail: ai-gateway/llm-proxy/guardrails/pii-masking-regex.md + - Regex guardrail: ai-gateway/llm-proxy/guardrails/regex.md + - Semantic prompt guardrail: ai-gateway/llm-proxy/guardrails/semantic-prompt-guard.md + - Sentence count guardrail: ai-gateway/llm-proxy/guardrails/sentence-count.md + - URL guardrail: ai-gateway/llm-proxy/guardrails/url.md + - Word count guardrail: ai-gateway/llm-proxy/guardrails/word-count.md + - Load balancing: + - Model round robin: ai-gateway/llm-proxy/load-balancing/model-round-robin.md + - Model weighted round robin: ai-gateway/llm-proxy/load-balancing/model-weighted-round-robin.md + - Prompt management: + - Prompt decorator: ai-gateway/llm-proxy/prompt-management/prompt-decorator.md + - Prompt template: ai-gateway/llm-proxy/prompt-management/prompt-template.md + - Semantic caching: ai-gateway/llm-proxy/semantic-caching.md + - MCP proxy: + - Quick start guide: ai-gateway/mcp-proxy/quick-start-guide.md - Policies: - - MCP Access Control List: ai-gateway/mcp-proxy/policies/mcp-acl-list.md - - MCP Authentication: ai-gateway/mcp-proxy/policies/mcp-authentication.md - - MCP Authorization: ai-gateway/mcp-proxy/policies/mcp-authorization.md - - MCP Rewrite: ai-gateway/mcp-proxy/policies/mcp-rewrite.md - - Deployment Modes: - - Immutable Gateway: ai-gateway/deployment-modes/immutable-gateway.md + - MCP access control list: ai-gateway/mcp-proxy/policies/mcp-acl-list.md + - MCP authentication: ai-gateway/mcp-proxy/policies/mcp-authentication.md + - MCP authorization: ai-gateway/mcp-proxy/policies/mcp-authorization.md + - MCP rewrite: ai-gateway/mcp-proxy/policies/mcp-rewrite.md + - Deployment modes: + - Immutable gateway: ai-gateway/deployment-modes/immutable-gateway.md - Kubernetes: - Overview: ai-gateway/deployment-modes/kubernetes/overview.md - - Standalone Mode: ai-gateway/deployment-modes/kubernetes/kubernetes-standalone.md - - Kubernetes Operator Mode: ai-gateway/deployment-modes/kubernetes/gateway-operator.md + - Standalone mode: ai-gateway/deployment-modes/kubernetes/kubernetes-standalone.md + - Kubernetes operator mode: ai-gateway/deployment-modes/kubernetes/gateway-operator.md - Observability: - Logging: ai-gateway/observability/logging.md - Tracing: ai-gateway/observability/tracing.md - Analytics: - - Moesif Analytics: ai-gateway/analytics/moesif-analytics.md - - Analytics Header Filter: ai-gateway/analytics/analytics-header-filter.md - - Analytics & Monetization: + - Moesif analytics: ai-gateway/analytics/moesif-analytics.md + - Analytics header filter: ai-gateway/analytics/analytics-header-filter.md + - Analytics & monetization: - Overview: analytics-and-monetization/overview.md - - Policy Hub: + - Policy hub: - Overview: policy-hub/overview.md - Guides: - AI and MCP: @@ -466,23 +466,23 @@ nav: - Developer Portal: - Go from Zero to a Working API Call Using the Developer Portal: guides/developer-portal/api-discovery-and-tryout.md - Samples: - - LLM Proxy - Token Based Rate Limiting: samples/ai-gw-llm-proxy-sample-overview.md - - LLM Provider and Proxy - AI Policies for Privacy and Cost Control: samples/AI-gateway-and-llm-failover.md + - LLM proxy - token based rate limiting: samples/ai-gw-llm-proxy-sample-overview.md + - LLM provider and proxy - AI policies for privacy and cost control: samples/AI-gateway-and-llm-failover.md - Tools: - API Platform CLI: - - Quick Start Guide: tools/cli/quick-start-guide.md - - Customizing Gateway Policies: tools/cli/customizing-gateway-policies.md + - Quick start guide: tools/cli/quick-start-guide.md + - Customizing gateway policies: tools/cli/customizing-gateway-policies.md - Reference: tools/cli/reference.md - - VS Code for API Design: - - Getting Started: tools/vscode-api-design/getting-started.md + - VS Code for API design: + - Getting started: tools/vscode-api-design/getting-started.md - Design APIs: tools/vscode-api-design/design-apis.md - Govern APIs: tools/vscode-api-design/govern-apis.md - - End-to-End Tutorial: tools/vscode-api-design/end-to-end-tutorial.md - - Arazzo MCP Generator CLI: - - Quick Start Guide: tools/arazzo-mcp-gen-cli/quick-start-guide.md + - End-to-end tutorial: tools/vscode-api-design/end-to-end-tutorial.md + - Arazzo MCP generator CLI: + - Quick start guide: tools/arazzo-mcp-gen-cli/quick-start-guide.md - Reference: tools/arazzo-mcp-gen-cli/reference.md - - VS Code Arazzo Visualizer: - - Getting Started: tools/vscode-arazzo-visualizer/getting-started.md + - VS Code Arazzo visualizer: + - Getting started: tools/vscode-arazzo-visualizer/getting-started.md # Extensions markdown_extensions: @@ -771,13 +771,13 @@ extra: options: - verticle-line - divider - - title: MCP Servers + - title: MCP servers options: - verticle-line-only - - title: Monitor and Insights + - title: Monitor and insights options: - verticle-line-only - - title: API Monetization + - title: API monetization options: - verticle-line-only - title: Administer @@ -802,11 +802,11 @@ extra: options: - verticle-line - divider - - title: Analytics & Monetization + - title: Analytics & monetization options: - verticle-line - divider - - title: Policy Hub + - title: Policy hub options: - verticle-line - divider @@ -829,7 +829,7 @@ extra: Overview: icon: octicons/apps-16 level: 1 - Get Started: + Get started: icon: octicons/rocket-16 level: 1 Cloud: @@ -847,22 +847,22 @@ extra: Introduction: icon: octicons/info-16 level: 1 - API Platform Samples: + API Platform samples: icon: octicons/file-code-16 level: 1 Tutorials: icon: octicons/mortar-board-16 level: 1 - Create API Proxy: + Create API proxy: icon: octicons/pencil-16 level: 1 - Develop API Proxy: + Develop API proxy: icon: octicons/tools-16 level: 1 - Test API Proxy: + Test API proxy: icon: octicons/bug-16 level: 1 - MCP Servers: + MCP servers: icon: octicons/server-16 level: 1 AI Gateway: @@ -877,10 +877,10 @@ extra: API Gateway: icon: octicons/globe-16 level: 1 - Monitor and Insights: + Monitor and insights: icon: octicons/graph-16 level: 1 - API Monetization: + API monetization: icon: octicons/credit-card-16 level: 1 Administer: @@ -892,12 +892,12 @@ extra: Developer Portal: icon: octicons/book-16 level: 1 - Analytics & Monetization: + Analytics & monetization: icon: octicons/graph-16 level: 1 API Manager: icon: octicons/sliders-16 - Policy Hub: + Policy hub: icon: octicons/package-16 #site_version: 1.0.0