openapi: 3.0.3
info:
title: NGINX njs Scripting Connections Stream Upstreams API
version: '0.8'
description: The NGINX njs module provides a JavaScript runtime embedded inside NGINX. It does not expose HTTP endpoints itself. Instead, it offers scripting objects (HTTP request, stream session, Fetch API, etc.) that are available within njs handler functions configured in the NGINX configuration file. This specification documents the key njs objects as OpenAPI schemas only; the paths object is intentionally empty because there are no REST endpoints to describe.
x-generated-from: documentation
contact:
name: NGINX
url: https://nginx.org/en/docs/njs/reference.html
license:
name: BSD-2-Clause
url: https://nginx.org/LICENSE
tags:
- name: Stream Upstreams
paths:
/stream/upstreams/:
get:
tags:
- Stream Upstreams
summary: NGINX Return Status of All Stream Upstream Server Groups
description: Returns status of each stream upstream server group and its servers.
operationId: getStreamUpstreams
produces:
- application/json
parameters:
- name: fields
in: query
type: string
description: Limits which fields of upstream server groups will be output. If the “<literal>fields</literal>” value is empty, only names of upstreams will be output.
x-example: ''
responses:
'200':
description: Success
schema:
$ref: '#/definitions/NginxStreamUpstreamMap'
examples:
application/json:
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
x-microcks-refs:
- name: getStreamUpstreams200Example
x-microcks-default: true
'404':
description: Unknown version (*UnknownVersion*)
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: {}
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: getStreamUpstreams404Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/stream/upstreams/{streamUpstreamName}/:
parameters:
- name: streamUpstreamName
in: path
description: The name of a stream upstream server group.
required: true
type: string
x-example: example_streamUpstreamName
get:
tags:
- Stream Upstreams
summary: NGINX Return Status of a Stream Upstream Server Group
description: Returns status of a particular stream upstream server group and its servers.
operationId: getStreamUpstream
produces:
- application/json
parameters:
- name: fields
in: query
type: string
description: Limits which fields of the upstream server group will be output.
x-example: ''
responses:
'200':
description: Success
schema:
$ref: '#/definitions/NginxStreamUpstream'
examples:
application/json:
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
x-microcks-refs:
- name: getStreamUpstream200Example
x-microcks-default: true
'400':
description: Upstream is static (*UpstreamStatic*)
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: &id001 {}
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: getStreamUpstream400Example
x-microcks-default: true
'404':
description: 'Unknown version (*UnknownVersion*),
upstream not found (*UpstreamNotFound*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id001
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: getStreamUpstream404Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
tags:
- Stream Upstreams
summary: NGINX Reset Statistics of a Stream Upstream Server Group
description: Resets the statistics for each upstream server in an upstream server group.
operationId: deleteStreamUpstreamStat
produces:
- application/json
responses:
'204':
description: Success
'400':
description: Upstream is static (*UpstreamStatic*)
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: &id002 {}
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: deleteStreamUpstreamStat400Example
x-microcks-default: true
'404':
description: 'Unknown version (*UnknownVersion*),
upstream not found (*UpstreamNotFound*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id002
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: deleteStreamUpstreamStat404Example
x-microcks-default: true
'405':
description: Method disabled (*MethodDisabled*)
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id002
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: deleteStreamUpstreamStat405Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/stream/upstreams/{streamUpstreamName}/servers/:
parameters:
- name: streamUpstreamName
in: path
description: The name of an upstream server group.
required: true
type: string
x-example: example_streamUpstreamName
get:
tags:
- Stream Upstreams
summary: NGINX 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
produces:
- application/json
responses:
'200':
description: Success
schema:
$ref: '#/definitions/NginxStreamUpstreamConfServerMap'
examples:
application/json:
- 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
x-microcks-refs:
- name: getStreamUpstreamServers200Example
x-microcks-default: true
'400':
description: Upstream is static (*UpstreamStatic*)
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: &id003 {}
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: getStreamUpstreamServers400Example
x-microcks-default: true
'404':
description: 'Unknown version (*UnknownVersion*),
upstream not found (*UpstreamNotFound*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id003
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: getStreamUpstreamServers404Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
tags:
- Stream Upstreams
summary: NGINX 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
produces:
- application/json
parameters:
- in: body
name: postStreamUpstreamServer
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
schema:
$ref: '#/definitions/NginxStreamUpstreamConfServer'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/NginxStreamUpstreamConfServer'
examples:
application/json:
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
x-microcks-refs:
- name: postStreamUpstreamServer201Example
x-microcks-default: true
'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*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: &id004 {}
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: postStreamUpstreamServer400Example
x-microcks-default: true
'404':
description: 'Unknown version (*UnknownVersion*),
upstream not found (*UpstreamNotFound*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id004
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: postStreamUpstreamServer404Example
x-microcks-default: true
'405':
description: Method disabled (*MethodDisabled*)
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id004
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: postStreamUpstreamServer405Example
x-microcks-default: true
'409':
description: Entry exists (*EntryExists*)
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id004
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: postStreamUpstreamServer409Example
x-microcks-default: true
'415':
description: JSON error (*JsonError*)
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id004
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: postStreamUpstreamServer415Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/stream/upstreams/{streamUpstreamName}/servers/{streamUpstreamServerId}:
parameters:
- name: streamUpstreamName
in: path
description: The name of the upstream server group.
required: true
type: string
x-example: example_streamUpstreamName
- name: streamUpstreamServerId
in: path
description: The ID of the server.
required: true
type: string
x-example: example_streamUpstreamServerId
get:
tags:
- Stream Upstreams
summary: NGINX 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
produces:
- application/json
responses:
'200':
description: Success
schema:
$ref: '#/definitions/NginxStreamUpstreamConfServer'
examples:
application/json:
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
x-microcks-refs:
- name: getStreamUpstreamServer200Example
x-microcks-default: true
'400':
description: 'Upstream is static (*UpstreamStatic*),
invalid server ID (*UpstreamBadServerId*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: &id005 {}
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: getStreamUpstreamServer400Example
x-microcks-default: true
'404':
description: 'Unknown version (*UnknownVersion*),
upstream not found (*UpstreamNotFound*),
server with ID “**id**” does not exist (*UpstreamServerNotFound*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id005
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: getStreamUpstreamServer404Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
tags:
- Stream Upstreams
summary: NGINX 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
produces:
- application/json
parameters:
- in: body
name: patchStreamUpstreamServer
description: Server parameters, specified in the JSON format. The “*ID*”, “*backup*”, and “*service*” parameters cannot be changed.
required: true
schema:
$ref: '#/definitions/NginxStreamUpstreamConfServer'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/NginxStreamUpstreamConfServer'
examples:
application/json:
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
x-microcks-refs:
- name: patchStreamUpstreamServer200Example
x-microcks-default: true
'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*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: &id006 {}
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: patchStreamUpstreamServer400Example
x-microcks-default: true
'404':
description: 'Server with ID “**id**” does not exist (*UpstreamServerNotFound*),
unknown version (*UnknownVersion*),
upstream not found (*UpstreamNotFound*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id006
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: patchStreamUpstreamServer404Example
x-microcks-default: true
'405':
description: Method disabled (*MethodDisabled*)
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id006
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: patchStreamUpstreamServer405Example
x-microcks-default: true
'415':
description: JSON error (*JsonError*)
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id006
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: patchStreamUpstreamServer415Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
tags:
- Stream Upstreams
summary: NGINX Remove a Server from a Stream Upstream Server Group
description: Removes a server from a stream server group.
operationId: deleteStreamUpstreamServer
produces:
- application/json
responses:
'200':
description: Success
schema:
$ref: '#/definitions/NginxStreamUpstreamConfServerMap'
examples:
application/json:
- 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
x-microcks-refs:
- name: deleteStreamUpstreamServer200Example
x-microcks-default: true
'400':
description: 'Upstream is static (*UpstreamStatic*),
invalid server ID (*UpstreamBadServerId*),
server “**id**” not removable (*UpstreamServerImmutable*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: &id007 {}
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: deleteStreamUpstreamServer400Example
x-microcks-default: true
'404':
description: 'Server with ID “**id**” does not exist (*UpstreamServerNotFound*),
unknown version (*UnknownVersion*),
upstream not found (*UpstreamNotFound*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id007
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: deleteStreamUpstreamServer404Example
x-microcks-default: true
'405':
description: Method disabled (*MethodDisabled*)
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id007
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: deleteStreamUpstreamServer405Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
definitions:
NginxStreamUpstreamPeer:
title: Stream Upstream Server
type: object
properties:
id:
type: integer
description: The ID of the server.
readOnly: true
example: 0
server:
type: string
description: An <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">address</a> of the server.
example: example-server
service:
type: string
description: The <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#service">service</a> parameter value of the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</a> directive.
example: example-service
name:
type: string
format: hostname
description: The name of the server specified in the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</a> directive.
readOnly: true
example: my_shared_zone
backup:
type: boolean
description: A boolean value indicating whether the server is a <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#backup">backup</a> server.
example: false
weight:
type: integer
description: <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#weight">Weight</a> of the server.
example: 0
state:
type: string
readOnly: true
enum:
- up
- down
- unavail
- checking
- unhealthy
description: Current state, which may be one of “<code>up</code>”, “<code>down</code>”, “<code>unavail</code>”, “<code>checking</code>”, or “<code>unhealthy</code>”.
example: example-state
active:
type: integer
description: The current number of connections.
readOnly: true
example: 5
ssl:
type: object
readOnly: true
properties:
handshakes:
type: integer
description: The total number of successful SSL handshakes.
readOnly: true
example: 79572
handshakes_failed:
type: integer
description: The total number of failed SSL handshakes.
readOnly: true
example: 21025
session_reuses:
type: integer
description: The total number of session reuses during SSL handshake.
readOnly: true
example: 15762
no_common_protocol:
type: integer
description: The number of SSL handshakes failed because of no common protocol.
example: 4
handshake_timeout:
type: integer
description: The number of SSL handshakes failed because of a timeout.
example: 0
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.
example: 0
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.
example: 2
revoked_cert:
type: integer
description: A revoked certificate was presented by an upstream server.
example: 1
hostname_mismatch:
type: integer
description: Server's certificate doesn't match the hostname.
example: 2
other:
type: integer
description: Other SSL certificate verification errors.
example: 1
example: {}
example: {}
max_conns:
type: integer
description: The <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_conns">max_conns</a> limit for the server.
example: 0
connections:
type: integer
description: The total number of client connections forwarded to this server.
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nginx/refs/heads/main/openapi/nginx-stream-upstreams-api-openapi.yml