openapi: 3.2.0
info:
version: '9.0'
title: NGINX Plus REST Stream Upstreams API
description: NGINX Plus REST API provides access to NGINX Plus status information, on-the-fly configuration of upstream servers and key-value pairs management for http and stream.
servers:
- url: /api/9
tags:
- name: Stream Upstreams
paths:
/stream/upstreams/:
get:
tags:
- Stream Upstreams
summary: Return status of all stream upstream server groups
description: Returns status of each stream upstream server group and its servers.
operationId: getStreamUpstreams
parameters:
- name: fields
in: query
description: Limits which fields of upstream server groups will be output. If the “fields” value is empty, only names of upstreams will be output.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/NginxStreamUpstreamMap'
'404':
description: Unknown version (*UnknownVersion*)
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
/stream/upstreams/{streamUpstreamName}/:
parameters:
- name: streamUpstreamName
in: path
description: The name of a stream upstream server group.
required: true
schema:
type: string
get:
tags:
- Stream Upstreams
summary: Return status of a stream upstream server group
description: Returns status of a particular stream upstream server group and its servers.
operationId: getStreamUpstream
parameters:
- name: fields
in: query
description: Limits which fields of the upstream server group will be output.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/NginxStreamUpstream'
'400':
description: Upstream is static (*UpstreamStatic*)
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
'404':
description: 'Unknown version (*UnknownVersion*),
upstream not found (*UpstreamNotFound*)
'
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
delete:
tags:
- Stream Upstreams
summary: Reset statistics of a stream upstream server group
description: Resets the statistics for each upstream server in an upstream server group.
operationId: deleteStreamUpstreamStat
responses:
'204':
description: Success
'400':
description: Upstream is static (*UpstreamStatic*)
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
'404':
description: 'Unknown version (*UnknownVersion*),
upstream not found (*UpstreamNotFound*)
'
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
'405':
description: Method disabled (*MethodDisabled*)
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
/stream/upstreams/{streamUpstreamName}/servers/:
parameters:
- name: streamUpstreamName
in: path
description: The name of an upstream server group.
required: true
schema:
type: string
get:
tags:
- Stream Upstreams
summary: Return configuration of all servers in a stream upstream server group
description: Returns configuration of each server in a particular stream upstream server group.
operationId: getStreamUpstreamServers
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/NginxStreamUpstreamConfServerMap'
'400':
description: Upstream is static (*UpstreamStatic*)
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
'404':
description: 'Unknown version (*UnknownVersion*),
upstream not found (*UpstreamNotFound*)
'
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
post:
tags:
- Stream Upstreams
summary: Add a server to a stream upstream server group
description: Adds a new server to a stream upstream server group. Server parameters are specified in the JSON format.
operationId: postStreamUpstreamServer
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/NginxStreamUpstreamConfServer'
'400':
description: 'Upstream is static (*UpstreamStatic*),
invalid “**parameter**” value (*UpstreamConfFormatError*),
missing “*server*” argument (*UpstreamConfFormatError*),
unknown parameter “**name**” (*UpstreamConfFormatError*),
nested object or list (*UpstreamConfFormatError*),
“*error*” while parsing (*UpstreamBadAddress*),
no port in server “*host*” (*UpstreamBadAddress*),
service upstream “*host*” may not have port (*UpstreamBadAddress*),
service upstream “*host*” requires domain name (*UpstreamBadAddress*),
invalid “*weight*” (*UpstreamBadWeight*),
invalid “*max_conns*” (*UpstreamBadMaxConns*),
invalid “*max_fails*” (*UpstreamBadMaxFails*),
invalid “*fail_timeout*” (*UpstreamBadFailTimeout*),
invalid “*slow_start*” (*UpstreamBadSlowStart*),
“*service*” is empty (*UpstreamBadService*),
no resolver defined to resolve (*UpstreamConfNoResolver*),
upstream “**name**” has no backup (*UpstreamNoBackup*),
upstream “**name**” memory exhausted (*UpstreamOutOfMemory*),
reading request body failed *BodyReadError*)
'
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
'404':
description: 'Unknown version (*UnknownVersion*),
upstream not found (*UpstreamNotFound*)
'
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
'405':
description: Method disabled (*MethodDisabled*)
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
'409':
description: Entry exists (*EntryExists*)
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
'415':
description: JSON error (*JsonError*)
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NginxStreamUpstreamConfServer'
description: Address of a new server and other optional parameters in the JSON format. The “*ID*”, “*backup*”, and “*service*” parameters cannot be changed.
required: true
/stream/upstreams/{streamUpstreamName}/servers/{streamUpstreamServerId}:
parameters:
- name: streamUpstreamName
in: path
description: The name of the upstream server group.
required: true
schema:
type: string
- name: streamUpstreamServerId
in: path
description: The ID of the server.
required: true
schema:
type: string
get:
tags:
- Stream Upstreams
summary: Return configuration of a server in a stream upstream server group
description: Returns configuration of a particular server in the stream upstream server group.
operationId: getStreamUpstreamServer
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/NginxStreamUpstreamConfServer'
'400':
description: 'Upstream is static (*UpstreamStatic*),
invalid server ID (*UpstreamBadServerId*)
'
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
'404':
description: 'Unknown version (*UnknownVersion*),
upstream not found (*UpstreamNotFound*),
server with ID “**id**” does not exist (*UpstreamServerNotFound*)
'
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
patch:
tags:
- Stream Upstreams
summary: Modify a server in a stream upstream server group
description: Modifies settings of a particular server in a stream upstream server group. Server parameters are specified in the JSON format.
operationId: patchStreamUpstreamServer
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/NginxStreamUpstreamConfServer'
'400':
description: 'Upstream is static (*UpstreamStatic*),
invalid “**parameter**” value (*UpstreamConfFormatError*),
unknown parameter “**name**” (*UpstreamConfFormatError*),
nested object or list (*UpstreamConfFormatError*),
“*error*” while parsing (*UpstreamBadAddress*),
invalid “*server*” argument (*UpstreamBadAddress*),
no port in server “*host*” (*UpstreamBadAddress*),
invalid server ID (*UpstreamBadServerId*),
invalid “*weight*” (*UpstreamBadWeight*),
invalid “*max_conns*” (*UpstreamBadMaxConns*),
invalid “*max_fails*” (*UpstreamBadMaxFails*),
invalid “*fail_timeout*” (*UpstreamBadFailTimeout*),
invalid “*slow_start*” (*UpstreamBadSlowStart*),
reading request body failed *BodyReadError*),
“*service*” is empty (*UpstreamBadService*),
server “**ID**” address is immutable (*UpstreamServerImmutable*),
server “**ID**” weight is immutable (*UpstreamServerWeightImmutable*),
upstream “*name*” memory exhausted (*UpstreamOutOfMemory*)
'
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
'404':
description: 'Server with ID “**id**” does not exist (*UpstreamServerNotFound*),
unknown version (*UnknownVersion*),
upstream not found (*UpstreamNotFound*)
'
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
'405':
description: Method disabled (*MethodDisabled*)
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
'415':
description: JSON error (*JsonError*)
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NginxStreamUpstreamConfServer'
description: Server parameters, specified in the JSON format. The “*ID*”, “*backup*”, and “*service*” parameters cannot be changed.
required: true
delete:
tags:
- Stream Upstreams
summary: Remove a server from a stream upstream server group
description: Removes a server from a stream server group.
operationId: deleteStreamUpstreamServer
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/NginxStreamUpstreamConfServerMap'
'400':
description: 'Upstream is static (*UpstreamStatic*),
invalid server ID (*UpstreamBadServerId*),
server “**id**” not removable (*UpstreamServerImmutable*)
'
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
'404':
description: 'Server with ID “**id**” does not exist (*UpstreamServerNotFound*),
unknown version (*UnknownVersion*),
upstream not found (*UpstreamNotFound*)
'
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
'405':
description: Method disabled (*MethodDisabled*)
content:
application/json:
schema:
$ref: '#/components/schemas/NginxError'
components:
schemas:
NginxError:
title: Error
description: 'nginx error object.
'
type: object
properties:
error:
type: object
properties:
status:
type: integer
description: HTTP error code.
text:
type: string
description: Error description.
code:
type: string
description: Internal nginx error code.
request_id:
type: string
description: The ID of the request, equals the value of the $request_id variable.
href:
type: string
description: Link to reference documentation.
NginxStreamUpstreamConfServer:
title: Stream Upstream Server
description: 'Dynamically configurable parameters of a stream upstream
server:
'
type: object
properties:
id:
type: integer
description: The ID of the stream upstream server. The ID is assigned automatically and cannot be changed.
readOnly: true
server:
type: string
description: Same as the address parameter of the stream upstream server. When adding a server, it is possible to specify it as a domain name. In this case, changes of the IP addresses that correspond to a domain name will be monitored and automatically applied to the upstream configuration without the need of restarting nginx. This requires the resolver directive in the “stream” block. See also the resolve parameter of the stream upstream server.
service:
type: string
description: Same as the service parameter of the stream upstream server. This parameter cannot be changed.
readOnly: true
weight:
type: integer
description: Same as the weight parameter of the stream upstream server.
max_conns:
type: integer
description: Same as the max_conns parameter of the stream upstream server.
max_fails:
type: integer
description: Same as the max_fails parameter of the stream upstream server.
fail_timeout:
type: string
description: Same as the fail_timeout parameter of the stream upstream server.
slow_start:
type: string
description: Same as the slow_start parameter of the stream upstream server.
backup:
type: boolean
description: When true, adds a backup server. This parameter cannot be changed.
readOnly: true
down:
type: boolean
description: Same as the down parameter of the stream upstream server.
parent:
type: string
description: Parent server ID of the resolved server. The ID is assigned automatically and cannot be changed.
readOnly: true
host:
type: string
description: Hostname of the resolved server. The hostname is assigned automatically and cannot be changed.
readOnly: true
example:
id: 0
server: 10.0.0.1:12348
weight: 1
max_conns: 0
max_fails: 1
fail_timeout: 10s
slow_start: 0
backup: false
down: false
NginxStreamUpstream:
title: Stream Upstream
type: object
properties:
peers:
$ref: '#/components/schemas/NginxStreamUpstreamPeerMap'
zombies:
type: integer
description: The current number of servers removed from the group but still processing active client connections.
zone:
type: string
description: The name of the shared memory zone that keeps the group’s configuration and run-time state.
example:
dns:
peers:
- id: 0
server: 10.0.0.1:12347
name: 10.0.0.1:12347
backup: false
weight: 5
state: up
active: 0
ssl:
handshakes: 200
handshakes_failed: 4
session_reuses: 189
no_common_protocol: 4
handshake_timeout: 0
peer_rejected_cert: 0
verify_failures:
expired_cert: 2
revoked_cert: 1
hostname_mismatch: 2
other: 1
max_conns: 50
connections: 667231
sent: 251946292
received: 19222475454
fails: 0
unavail: 0
health_checks:
checks: 26214
fails: 0
unhealthy: 0
last_passed: true
downtime: 0
downstart: 2022-06-28 11:09:21.602000+00:00
selected: 2022-06-28 15:01:25+00:00
- id: 1
server: 10.0.0.1:12348
name: 10.0.0.1:12348
backup: true
weight: 1
state: unhealthy
active: 0
max_conns: 50
connections: 0
sent: 0
received: 0
fails: 0
unavail: 0
health_checks:
checks: 26284
fails: 26284
unhealthy: 1
last_passed: false
downtime: 262925617
downstart: 2022-06-28 11:09:21.602000+00:00
selected: 2022-06-28 15:01:25+00:00
zombies: 0
zone: dns
NginxStreamUpstreamPeerMap:
title: Stream Upstream Servers
description: Array of stream upstream servers.
type: array
items:
$ref: '#/components/schemas/NginxStreamUpstreamPeer'
NginxStreamUpstreamMap:
title: Stream Upstreams
description: Status information of stream upstream server groups.
type: object
additionalProperties:
$ref: '#/components/schemas/NginxStreamUpstream'
example:
mysql_backends:
peers:
- id: 0
server: 10.0.0.1:12345
name: 10.0.0.1:12345
backup: false
weight: 5
state: up
active: 0
ssl:
handshakes: 1045
handshakes_failed: 89
session_reuses: 321
no_common_protocol: 4
handshake_timeout: 0
peer_rejected_cert: 0
verify_failures:
expired_cert: 2
revoked_cert: 1
hostname_mismatch: 2
other: 1
max_conns: 30
connecions: 1231
sent: 251946292
received: 19222475454
fails: 0
unavail: 0
health_checks:
checks: 26214
fails: 0
unhealthy: 0
last_passed: true
downtime: 0
downstart: 2022-06-28 11:09:21.602000+00:00
selected: 2022-06-28 15:01:25+00:00
- id: 1
server: 10.0.0.1:12346
name: 10.0.0.1:12346
backup: true
weight: 1
state: unhealthy
active: 0
max_conns: 30
connections: 0
sent: 0
received: 0
fails: 0
unavail: 0
health_checks:
checks: 26284
fails: 26284
unhealthy: 1
last_passed: false
downtime: 262925617
downstart: 2022-06-28 11:09:21.602000+00:00
selected: 2022-06-28 15:01:25+00:00
zombies: 0
zone: mysql_backends
dns:
peers:
- id: 0
server: 10.0.0.1:12347
name: 10.0.0.1:12347
backup: false
weight: 5
state: up
active: 0
ssl:
handshakes: 5268
handshakes_failed: 121
session_reuses: 854
no_common_protocol: 4
handshake_timeout: 0
peer_rejected_cert: 0
verify_failures:
expired_cert: 2
revoked_cert: 1
hostname_mismatch: 2
other: 1
max_conns: 30
connections: 667231
sent: 251946292
received: 19222475454
fails: 0
unavail: 0
health_checks:
checks: 26214
fails: 0
unhealthy: 0
last_passed: true
downtime: 0
downstart: 2022-06-28 11:09:21.602000+00:00
selected: 2022-06-28 15:01:25+00:00
- id: 1
server: 10.0.0.1:12348
name: 10.0.0.1:12348
backup: true
weight: 1
state: unhealthy
active: 0
connections: 0
max_conns: 30
sent: 0
received: 0
fails: 0
unavail: 0
health_checks:
checks: 26284
fails: 26284
unhealthy: 1
last_passed: false
downtime: 262925617
downstart: 2022-06-28 11:09:21.602000+00:00
selected: 2022-06-28 15:01:25+00:00
zombies: 0
zone: dns
NginxStreamUpstreamConfServerMap:
title: Stream Upstream Servers
description: 'An array of stream upstream servers for dynamic configuration.
'
type: array
items:
$ref: '#/components/schemas/NginxStreamUpstreamConfServer'
example:
- id: 0
server: 10.0.0.1:12348
weight: 1
max_conns: 0
max_fails: 1
fail_timeout: 10s
slow_start: 0
backup: false
down: false
- id: 1
server: 10.0.0.1:12349
weight: 1
max_conns: 0
max_fails: 1
fail_timeout: 10s
slow_start: 0
backup: false
down: false
NginxStreamUpstreamPeer:
title: Stream Upstream Server
type: object
properties:
id:
type: integer
description: The ID of the server.
readOnly: true
server:
type: string
description: An address of the server.
service:
type: string
description: The service parameter value of the server directive.
name:
type: string
format: hostname
description: The name of the server specified in the server directive.
readOnly: true
backup:
type: boolean
description: A boolean value indicating whether the server is a backup server.
weight:
type: integer
description: Weight of the server.
state:
type: string
readOnly: true
enum:
- up
- down
- unavail
- checking
- unhealthy
description: Current state, which may be one of “up”, “down”, “unavail”, “checking”, or “unhealthy”.
active:
type: integer
description: The current number of connections.
readOnly: true
ssl:
type: object
readOnly: true
properties:
handshakes:
type: integer
description: The total number of successful SSL handshakes.
readOnly: true
handshakes_failed:
type: integer
description: The total number of failed SSL handshakes.
readOnly: true
session_reuses:
type: integer
description: The total number of session reuses during SSL handshake.
readOnly: true
no_common_protocol:
type: integer
description: The number of SSL handshakes failed because of no common protocol.
handshake_timeout:
type: integer
description: The number of SSL handshakes failed because of a timeout.
peer_rejected_cert:
type: integer
description: The number of failed SSL handshakes when nginx presented the certificate to the upstream server but it was rejected with a corresponding alert message.
verify_failures:
type: object
description: SSL certificate verification errors
properties:
expired_cert:
type: integer
description: An expired or not yet valid certificate was presented by an upstream server.
revoked_cert:
type: integer
description: A revoked certificate was presented by an upstream server.
hostname_mismatch:
type: integer
description: Server's certificate doesn't match the hostname.
other:
type: integer
description: Other SSL certificate verification errors.
max_conns:
type: integer
description: The max_conns limit for the server.
connections:
type: integer
description: The total number of client connections forwarded to this server.
readOnly: true
connect_time:
type: integer
description: The average time to connect to the upstream server.
readOnly: true
first_byte_time:
type: integer
description: The average time to receive the first byte of data.
readOnly: true
response_time:
type: integer
description: The average time to receive the last byte of data.
readOnly: true
sent:
type: integer
description: The total number of bytes sent to this server.
readOnly: true
received:
type: integer
description: The total number of bytes received from this server.
readOnly: true
fails:
type: integer
description: The total number of unsuccessful attempts to communicate with the server.
readOnly: true
unavail:
type: integer
description: How many times the server became unavailable for client connections (state “unavail”) due to the number of unsuccessful attempts reaching the max_fails threshold.
readOnly: true
health_checks:
type: object
readOnly: true
properties:
checks:
type: integer
description: The total number of health check requests made.
readOnly: true
fails:
type: integer
description: The number of failed health checks.
readOnly: true
unhealthy:
type: integer
description: How many times the server became unhealthy (state “unhealthy”).
readOnly: true
last_passed:
type: boolean
description: Boolean indicating whether the last health check request was successful and passed tests.
readOnly: true
downtime:
type: integer
description: Total time the server was in the “unavail”, “checking”, and “unhealthy” states.
readOnly: true
downstart:
type: string
format: date-time
description: The time when the server became “unavail”, “checking”, or “unhealthy”, in the ISO 8601 format with millisecond resolution.
readOnly: true
selected:
type: string
format: date-time
description: The time when the server was last selected to process a connection, in the ISO 8601 format with millisecond resolution.
readOnly: true