Skip to content

Document global Backends for the next API Gateway release - #840

Open
CrowleyRajapakse wants to merge 2 commits into
wso2:mainfrom
CrowleyRajapakse:docs/global-backends
Open

CrowleyRajapakse wants to merge 2 commits into
wso2:mainfrom
CrowleyRajapakse:docs/global-backends

Conversation

@CrowleyRajapakse

Copy link
Copy Markdown
Contributor

Draft until the gateway changes merge. This documents the global Backends feature of the next API Gateway release, implemented in wso2/api-platform#4264, wso2/api-platform#4265 and wso2/gateway-controllers#414. I will mark it ready once those PRs are merged.

Purpose

API Platform Gateway gains a gateway-wide Backend resource: a backend defined once for the whole gateway that any API can route to by name, or by a value taken from the request, through the dynamic-endpoint policy (v1.1), without editing or redeploying the API. The next release's documentation has no page for it, and the management API reference, release notes and policies overview don't mention it.

Checklist

  • Verified that llms.txt (located at en/docs/llms.txt) is updated for AI readiness content. Not updated: llms.txt lists the released API Gateway versions only and has no next entries; the pages should be added when this release is published.
  • Ensured meaningful alt text for images and that the information contained in an image also appears in text so the relevant info exists in the body of the document. No images are added.
  • Added or updated frontmatter for the respective pages.

Goals

  • A guide that explains what a Backend is, how to create and manage one, and how APIs route to it.
  • A management API reference for /backends, consistent with the other reference pages.
  • Release notes and the policies overview that mention the feature.

Approach

All changes are in the next version of the API Gateway docs.

  • api-gateway/next/backends/global-backends.md (new, nav: API Gateway → next → Backends → Global Backends):
    • what a Backend is, its use cases and how routing works (each Backend is its own upstream, the API's own upstream definitions take precedence, the Backend's base path replaces the API's, requests fail closed, Backends belong to one gateway);
    • the Backend YAML (apiVersion: gateway.choreolabs.com/v1) and a field reference;
    • creating it with ap gateway apply or POST /backends, and the roles that may change it;
    • routing an API to Backends with a CEL backendExpression and backendSelector (with remove-headers keeping the routing header from the backend), onMissingValue, a fixed targetUpstream, and adding a Backend without changing the API;
    • mutual TLS (identity, trustedCAs, verifyHostName) and its warnings, update and delete (including the 409 while an API names it), immutable gateways, errors (400, 503/905008, 500/905005, 409) and limitations.
  • The policy itself is not documented here. The guide links to the Dynamic Endpoint page on Policy Hub, https://wso2.com/api-platform/policy-hub/policies/dynamic-endpoint, which serves v1.1 once that version is published (same link).
  • Management API: a Backend Management reference page, generated from the gateway controller OpenAPI the same way as the other reference pages (front matter added); the BackendRequest, Backend and BackendConfiguration schemas and the TLS_NO_TRUST_SOURCE warning code in schemas.md and the GraphQL API page's warning codes; a Backend Management section in the management API overview.
  • Release notes: a "Global Backends" entry under new features and a Dynamic Endpoint v1.1 entry under a new "Updated policies" heading.
  • Policies overview: the Dynamic Endpoint row mentions routing to Backends.
  • Navigation: mkdocs.yml entries for the two pages.

The pages follow the style rules in .claude/rules/doc-*.md. A glossary entry for "Backend" is left for the release itself, because the glossary isn't versioned and would otherwise describe an unreleased feature.

User stories

  • As a gateway operator, I learn how to define a backend once for the gateway and update or remove it without touching the APIs that use it.
  • As an API developer, I learn how to route requests to a Backend by name, by header or by another part of the request, and what the gateway returns when it can't.

Release note

Global Backends: define a backend once for the whole gateway with the Backend resource and route API requests to it with the Dynamic Endpoint policy, by name or by a CEL expression over the request context.

Documentation

This PR is the documentation.

Training

N/A

Certification

N/A — documentation for a feature not yet released.

Marketing

N/A

Automation tests

  • Unit tests

    N/A (documentation only)

  • Integration tests

    N/A (documentation only). mkdocs build succeeds with no warnings from the changed files, and every link on the new page resolves; the pages were checked with mkdocs serve.

Security checks

Samples

The guide includes a Backend definition, a REST API that routes by an x-tenant header, a fixed-target configuration and a mutual-TLS Backend.

Related PRs

Migrations (if applicable)

N/A

Test environment

MkDocs 1.4.2 with the repository's requirements.txt on Python 3.12, macOS.

Learning

N/A

🤖 Generated with Claude Code

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant