From e6e8d1864b0fa4973877ff9cb3b85f8ebf134041 Mon Sep 17 00:00:00 2001
From: mehara-rothila <rothilamehara22@gmail.com>
Date: Thu, 11 Jun 2026 23:46:02 +0530
Subject: [PATCH] feat(platform-api): add upstreamDefinitions pool to the REST
 API OpenAPI schema

Declare the API-level upstreamDefinitions pool (ReusableUpstream + UpstreamTimeout) so an upstream.ref can resolve against a named definition, mirroring the gateway's upstreamDefinitions shape. Schema only; model, converters, deployment-YAML emission, and validation follow.
---
 platform-api/src/resources/openapi.yaml | 59 +++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/platform-api/src/resources/openapi.yaml b/platform-api/src/resources/openapi.yaml
index e6e43fb55..262adb26e 100644
--- a/platform-api/src/resources/openapi.yaml
+++ b/platform-api/src/resources/openapi.yaml
@@ -6326,6 +6326,11 @@ components:
           example: "2023-10-12T10:30:00Z"
         upstream:
           $ref: "#/components/schemas/Upstream"
+        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
@@ -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:
+      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:
+          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
+              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
+
     ExtractionIdentifier:
       type: object
       required: