Skip to content

docs: backport terminology corrections to 3.17 - #14110

Open
kayx23 wants to merge 1 commit into
apache:release/3.17from
kayx23:docs/backport-terminology-317
Open

kayx23 wants to merge 1 commit into
apache:release/3.17from
kayx23:docs/backport-terminology-317

Conversation

@kayx23

@kayx23 kayx23 commented Oct 27, 2026 •

Copy link
Copy Markdown
Member

Summary

  • port the corrected APISIX key-concept explanations into release/3.17
  • preserve useful examples, configuration tables, and English and Chinese coverage
  • retain only behavior verified in the 3.17 source
  • keep the terminology work separate from the version-specific Admin API contract in docs: add source-verified 3.17 Admin API contract #14083

Why these corrections are needed

  • Consumer: the previous page treated a Consumer ID as its runtime identity and showed an Upstream attached to a Consumer, although 3.17 identifies Consumers by username and has no Consumer Upstream.
  • Credential: each Credential contains at most one authentication plugin, while a Consumer can hold multiple Credentials for different plugins or the same plugin with distinct identifying values.
  • Global Rule: global and local plugins are interleaved by phase rather than running every global plugin before every local plugin.
  • Plugin Metadata: shared logger log_format metadata has a defined fallback, but metadata does not have one universal precedence rule for every plugin and field.
  • Stream Route: 3.17 supports sni filtering but not the newer snis field, so this backport documents only sni.
  • Secret and router expressions: the existing text overstates plaintext protection and depends on API7-owned links and an iRESTY hostname.

Porting strategy

The detailed API7 APISIX key-concept pages were corrected and source-verified first. This PR adapts those corrections to the 3.17 source instead of copying newer branch behavior unchanged.

API7-hosted diagram assets are not embedded because the public Apache pages should not depend on API7 infrastructure. Their useful scenarios remain in prose. The removed Consumer diagram was technically inaccurate because it attached an Upstream to a Consumer.

#14105 should merge first. #14083 should merge after this terminology PR.

Validation

  • one clean commit containing 11 Markdown files
  • markdownlint on every changed Markdown file
  • repository-wide internal link checker
  • Chinese line-segmentation checker
  • git diff --check origin/release/3.17...HEAD
  • verified that the corrected scope introduces no API7 repository, CDN, or iRESTY dependencies
  • source audit against 3.17 schemas, Admin API handlers, Credential behavior, plugin metadata consumers, and global/local phase execution

@kayx23
kayx23 force-pushed the docs/backport-terminology-317 branch from 94513e1 to 6e7a529 Compare October 28, 2026 07:50
@kayx23
kayx23 marked this pull request as ready for review October 28, 2026 07:51
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.

3 participants