Skip to content

feat(platform-api): support API-level upstreamDefinitions pool #2155

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
mehara-rothila wants to merge 1 commit into
base: feature/operation-level-ep
Choose a base branch
from
Draft

feat(platform-api): support API-level upstreamDefinitions pool #2155

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions platform-api/src/resources/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6326,6 +6326,11 @@ components:
example: "2023-10-12T10:30:00Z"
upstream:
$ref: "#/components/schemas/Upstream"

@renuka-fernando renuka-fernando Jun 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

upstream should have to support ref as well right?

@mehara-rothila mehara-rothila Jun 14, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes , main/sandbox resolve to UpstreamDefinition (line 8374), which is oneOf: [url] | [ref], so main: { ref: my-upstream-1 } already works. Same shape as the gateway's Upstream in #2012.

upstreamDefinitions:
type: array
description: List of reusable named upstream definitions. API-level upstream `ref` values resolve against entries here by name.
items:
$ref: '#/components/schemas/ReusableUpstream'
lifeCycleStatus:
type: string
description: Current lifecycle status of the API
Expand Down Expand Up @@ -8404,6 +8409,60 @@ components:
description: Authentication value (API key, Bearer token, or Base64 encoded credentials for basic auth)
example: my-api-key-value

ReusableUpstream:

@renuka-fernando renuka-fernando Jun 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
ReusableUpstream:
UpstreamDefinition:

What about UpstreamDefinition here?
cc: @tharindu1st

@mehara-rothila mehara-rothila Jun 14, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tharindu1st @renuka-fernando this is a 3-way name swap, not a simple rename.

Today in openapi.yaml:

Schema Role Line
Upstream the {main, sandbox} wrapper L8363
UpstreamDefinition the url/ref endpoint L8374
ReusableUpstream the pool entry L8412

(Upstream is shared by API / LLMProvider / MCPServer / WebSub, so it has to stay.)

Two things point the same way:

  • The gateway-controller names the pool entry UpstreamDefinition (management-openapi.yaml#L4210).
  • Our internal model already uses UpstreamEndpoint (endpoint) + UpstreamDefinition (pool) , see platform-api/src/internal/model/upstream.go.

We can't fully match the gateway since it has no wrapper (it inlines {main, sandbox}).

Proposal: keep the Upstream wrapper, then rename:

  • endpoint UpstreamDefinition → UpstreamEndpoint
  • pool entry ReusableUpstream → UpstreamDefinition

This aligns the schema with both the gateway's pool name and our internal model. Good to proceed?

title: Reusable Upstream
type: object
required:
- name
- upstreams
description: A reusable named upstream definition. Referenced by name from an API-level upstream.ref.
properties:
name:
type: string
description: Unique identifier for this upstream definition
minLength: 1
maxLength: 100
pattern: '^[a-zA-Z0-9\-_]+$'
example: my-upstream-1
basePath:

@renuka-fernando renuka-fernando Jun 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pattern for basePath?

@mehara-rothila mehara-rothila Jun 14, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The gateway-controller validates upstream basePath in code (#2106), not via an OpenAPI pattern. Happy to add a matching pattern here for client-side validation , or keep it server-side to match the gateway. Which do you prefer?

type: string
description: Base path prefix prepended to all requests routed to this upstream (e.g., /api/v2)
example: /api/v2
timeout:
$ref: '#/components/schemas/UpstreamTimeout'
upstreams:
type: array
description: List of backend targets with optional weights for load balancing
minItems: 1
items:
type: object
additionalProperties: false
required:
- url
properties:
url:
type: string
format: uri
description: Backend URL (host and port only; path comes from basePath)
example: http://prod-backend-1:5000
Comment thread
coderabbitai[bot] marked this conversation as resolved.
weight:
type: integer
description: Weight for load balancing (optional, default 100)
minimum: 0
maximum: 100
example: 80

UpstreamTimeout:
title: Upstream Timeout
type: object
description: Timeout configuration for upstream requests
properties:
connect:
type: string
description: Connection timeout duration (e.g., "5s", "500ms")
pattern: '^\d+(\.\d+)?(ms|s|m|h)$'
example: 5s
Comment thread
coderabbitai[bot] marked this conversation as resolved.

ExtractionIdentifier:
type: object
required:
Expand Down
Loading