Apache APISIX Stream Routes API
Manage Layer 4 TCP/UDP stream routes.
OpenAPI Specification
openapi: 3.1.0
info:
title: Apache APISIX Admin Consumer Groups Stream Routes API
description: The Apache APISIX Admin API provides a RESTful interface to dynamically control and configure your deployed Apache APISIX instance. It allows management of routes, services, upstreams, consumers, SSL certificates, global rules, plugin configurations, consumer groups, secrets, and more. By default, the Admin API listens on port 9180 and requires API key authentication via the X-API-KEY header.
version: 3.14.0
contact:
name: Apache APISIX
url: https://apisix.apache.org
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: http://127.0.0.1:9180/apisix/admin
description: Default local Admin API server
security:
- apiKey: []
tags:
- name: Stream Routes
description: Manage Layer 4 TCP/UDP stream routes.
paths:
/stream_routes:
get:
operationId: listStreamRoutes
summary: Apache APISIX List All Stream Routes
description: Fetches a list of all configured stream (Layer 4) routes.
tags:
- Stream Routes
responses:
'200':
description: Successful response with list of stream routes.
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceList'
/stream_routes/{route_id}:
get:
operationId: getStreamRoute
summary: Apache APISIX Get a Stream Route
description: Fetches the specified stream route by its ID.
tags:
- Stream Routes
parameters:
- $ref: '#/components/parameters/StreamRouteId'
responses:
'200':
description: Successful response with stream route details.
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceResponse'
'404':
description: Stream route not found.
put:
operationId: createOrUpdateStreamRoute
summary: Apache APISIX Create or Update a Stream Route
description: Creates a stream route with the specified ID, or updates it if it already exists.
tags:
- Stream Routes
parameters:
- $ref: '#/components/parameters/StreamRouteId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StreamRoute'
responses:
'200':
description: Stream route updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceResponse'
'201':
description: Stream route created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceCreated'
delete:
operationId: deleteStreamRoute
summary: Apache APISIX Delete a Stream Route
description: Removes the specified stream route.
tags:
- Stream Routes
parameters:
- $ref: '#/components/parameters/StreamRouteId'
responses:
'200':
description: Stream route deleted successfully.
'404':
description: Stream route not found.
components:
schemas:
ResourceResponse:
type: object
description: Standard response wrapper for a single resource.
properties:
key:
type: string
description: The etcd key path for the resource.
value:
type: object
description: The resource configuration.
modifiedIndex:
type: integer
description: The etcd modification index.
createdIndex:
type: integer
description: The etcd creation index.
Timeout:
type: object
description: Timeout settings for upstream connections.
properties:
connect:
type: number
default: 60
description: Connection timeout in seconds.
send:
type: number
default: 60
description: Send timeout in seconds.
read:
type: number
default: 60
description: Read timeout in seconds.
ResourceCreated:
type: object
description: Response wrapper for a newly created resource.
properties:
key:
type: string
description: The etcd key path for the created resource.
value:
type: object
description: The created resource configuration.
ResourceList:
type: object
description: Standard response wrapper for a list of resources.
properties:
list:
type: array
items:
$ref: '#/components/schemas/ResourceResponse'
description: Array of resource entries.
total:
type: integer
description: Total count of resources.
Upstream:
type: object
description: An Upstream is a virtual host abstraction that performs load balancing on a given set of service nodes according to configured rules.
properties:
name:
type: string
description: Human-readable name for the upstream.
desc:
type: string
description: Description of the upstream.
type:
type: string
enum:
- roundrobin
- chash
- least_conn
- ewma
default: roundrobin
description: Load balancing algorithm.
nodes:
oneOf:
- type: object
additionalProperties:
type: integer
description: Key-value pairs of address:port to weight.
- type: array
items:
type: object
properties:
host:
type: string
port:
type: integer
weight:
type: integer
priority:
type: integer
default: 0
description: List of node objects.
description: Backend service nodes.
service_name:
type: string
description: Service name for service discovery.
discovery_type:
type: string
description: Type of service discovery (e.g. dns, consul, nacos, eureka).
hash_on:
type: string
enum:
- vars
- header
- cookie
- consumer
- vars_combinations
default: vars
description: Hash input for consistent hashing load balancer.
key:
type: string
description: Hash key when using chash load balancer.
checks:
type: object
description: Health check configuration.
properties:
active:
type: object
description: Active health check configuration.
properties:
type:
type: string
enum:
- http
- https
- tcp
default: http
timeout:
type: number
default: 1
http_path:
type: string
default: /
host:
type: string
port:
type: integer
https_verify_certificate:
type: boolean
default: true
healthy:
type: object
properties:
interval:
type: integer
successes:
type: integer
unhealthy:
type: object
properties:
interval:
type: integer
http_failures:
type: integer
tcp_failures:
type: integer
timeouts:
type: integer
passive:
type: object
description: Passive health check configuration.
properties:
type:
type: string
enum:
- http
- https
- tcp
default: http
healthy:
type: object
properties:
http_statuses:
type: array
items:
type: integer
successes:
type: integer
unhealthy:
type: object
properties:
http_statuses:
type: array
items:
type: integer
http_failures:
type: integer
tcp_failures:
type: integer
timeouts:
type: integer
retries:
type: integer
description: Number of retries for failed requests.
retry_timeout:
type: number
description: Timeout in seconds for retry requests.
timeout:
$ref: '#/components/schemas/Timeout'
scheme:
type: string
enum:
- http
- https
- grpc
- grpcs
default: http
description: The scheme for communicating with the upstream.
pass_host:
type: string
enum:
- pass
- node
- rewrite
default: pass
description: How to set the Host header when proxying to upstream.
upstream_host:
type: string
description: Host to use when pass_host is set to rewrite.
labels:
type: object
additionalProperties:
type: string
description: Key-value pairs for categorization.
keepalive_pool:
type: object
description: Keepalive pool configuration.
properties:
size:
type: integer
default: 320
idle_timeout:
type: number
default: 60
requests:
type: integer
default: 1000
tls:
type: object
description: TLS configuration for upstream connections.
properties:
client_cert:
type: string
description: Client certificate for mTLS.
client_key:
type: string
description: Client private key for mTLS.
StreamRoute:
type: object
description: A Stream Route is used for Layer 4 (TCP/UDP) traffic proxying.
properties:
desc:
type: string
description: Description of the stream route.
remote_addr:
type: string
description: Client IP address to match.
server_addr:
type: string
description: Server address to match.
server_port:
type: integer
description: Server port to match.
sni:
type: string
description: Server Name Indication value to match.
plugins:
type: object
description: Plugin configuration for the stream route.
upstream:
$ref: '#/components/schemas/Upstream'
upstream_id:
type: string
description: ID of an existing upstream to use.
parameters:
StreamRouteId:
name: route_id
in: path
required: true
description: Unique identifier of the stream route.
schema:
type: string
securitySchemes:
apiKey:
type: apiKey
in: header
name: X-API-KEY
description: Admin API key for authentication.