openapi: 3.0.3
info:
title: NGINX njs Scripting Connections HTTP 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: HTTP Upstreams
paths:
/http/upstreams/:
get:
tags:
- HTTP Upstreams
summary: NGINX Return Status of All HTTP Upstream Server Groups
description: Returns status of each HTTP upstream server group and its servers.
operationId: getHttpUpstreams
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/NginxHTTPUpstreamMap'
examples:
application/json:
trac-backend:
peers:
- id: 0
server: 10.0.0.1:8088
name: 10.0.0.1:8088
backup: false
weight: 5
state: up
active: 0
ssl:
handshakes: 620311
handshakes_failed: 3432
session_reuses: 36442
no_common_protocol: 4
handshake_timeout: 0
peer_rejected_cert: 0
verify_failures:
expired_cert: 2
revoked_cert: 1
hostname_mismatch: 2
other: 1
requests: 667231
header_time: 20
response_time: 36
responses:
1xx: 0
2xx: 666310
3xx: 0
4xx: 915
5xx: 6
codes:
200: 666310
404: 915
503: 6
total: 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:8089
name: 10.0.0.1:8089
backup: true
weight: 1
state: unhealthy
active: 0
requests: 0
responses:
1xx: 0
2xx: 0
3xx: 0
4xx: 0
5xx: 0
codes: {}
total: 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
keepalive: 0
zombies: 0
zone: trac-backend
hg-backend:
peers:
- id: 0
server: 10.0.0.1:8088
name: 10.0.0.1:8088
backup: false
weight: 5
state: up
active: 0
ssl:
handshakes: 620311
handshakes_failed: 3432
session_reuses: 36442
no_common_protocol: 4
handshake_timeout: 0
peer_rejected_cert: 0
verify_failures:
expired_cert: 2
revoked_cert: 1
hostname_mismatch: 2
other: 1
requests: 667231
header_time: 20
response_time: 36
responses:
1xx: 0
2xx: 666310
3xx: 0
4xx: 915
5xx: 6
codes:
200: 666310
404: 915
503: 6
total: 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:8089
name: 10.0.0.1:8089
backup: true
weight: 1
state: unhealthy
active: 0
requests: 0
responses:
1xx: 0
2xx: 0
3xx: 0
4xx: 0
5xx: 0
codes: {}
total: 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
keepalive: 0
zombies: 0
zone: hg-backend
x-microcks-refs:
- name: getHttpUpstreams200Example
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: getHttpUpstreams404Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/http/upstreams/{httpUpstreamName}/:
parameters:
- name: httpUpstreamName
in: path
description: The name of an HTTP upstream server group.
required: true
type: string
x-example: example_httpUpstreamName
get:
tags:
- HTTP Upstreams
summary: NGINX Return Status of an HTTP Upstream Server Group
description: Returns status of a particular HTTP upstream server group and its servers.
operationId: getHttpUpstreamName
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/NginxHTTPUpstream'
examples:
application/json:
upstream_backend:
peers:
- id: 0
server: 10.0.0.1:8088
name: 10.0.0.1:8088
backup: false
weight: 5
state: up
active: 0
ssl:
handshakes: 620311
handshakes_failed: 3432
session_reuses: 36442
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: 20
requests: 667231
header_time: 20
response_time: 36
responses:
1xx: 0
2xx: 666310
3xx: 0
4xx: 915
5xx: 6
codes:
200: 666310
404: 915
503: 6
total: 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:8089
name: 10.0.0.1:8089
backup: true
weight: 1
state: unhealthy
active: 0
max_conns: 20
requests: 0
responses:
1xx: 0
2xx: 0
3xx: 0
4xx: 0
5xx: 0
codes: {}
total: 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
keepalive: 0
zombies: 0
zone: upstream_backend
x-microcks-refs:
- name: getHttpUpstreamName200Example
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: getHttpUpstreamName400Example
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: getHttpUpstreamName404Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
tags:
- HTTP Upstreams
summary: NGINX Reset Statistics of an HTTP Upstream Server Group
description: Resets the statistics for each upstream server in an upstream server group and queue statistics.
operationId: deleteHttpUpstreamStat
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: deleteHttpUpstreamStat400Example
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: deleteHttpUpstreamStat404Example
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: deleteHttpUpstreamStat405Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/http/upstreams/{httpUpstreamName}/servers/:
parameters:
- name: httpUpstreamName
in: path
description: The name of an upstream server group.
required: true
type: string
x-example: example_httpUpstreamName
get:
tags:
- HTTP Upstreams
summary: NGINX Return Configuration of All Servers in an HTTP Upstream Server Group
description: Returns configuration of each server in a particular HTTP upstream server group.
operationId: getHttpUpstreamServers
produces:
- application/json
responses:
'200':
description: Success
schema:
$ref: '#/definitions/NginxHTTPUpstreamConfServerMap'
examples:
application/json:
- id: 0
server: 10.0.0.1:8088
weight: 1
max_conns: 0
max_fails: 0
fail_timeout: 10s
slow_start: 10s
route: ''
backup: false
down: false
- id: 1
server: 10.0.0.1:8089
weight: 4
max_conns: 0
max_fails: 0
fail_timeout: 10s
slow_start: 10s
route: ''
backup: true
down: true
x-microcks-refs:
- name: getHttpUpstreamServers200Example
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: getHttpUpstreamServers400Example
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: getHttpUpstreamServers404Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
tags:
- HTTP Upstreams
summary: NGINX Add a Server to an HTTP Upstream Server Group
description: Adds a new server to an HTTP upstream server group. Server parameters are specified in the JSON format.
operationId: postHttpUpstreamServer
produces:
- application/json
parameters:
- in: body
name: postHttpUpstreamServer
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/NginxHTTPUpstreamConfServer'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/NginxHTTPUpstreamConfServer'
examples:
application/json:
id: 1
server: 10.0.0.1:8089
weight: 4
max_conns: 0
max_fails: 0
fail_timeout: 10s
slow_start: 10s
route: ''
backup: true
down: true
x-microcks-refs:
- name: postHttpUpstreamServer201Example
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*),
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*),
reading request body failed *BodyReadError*),
route is too long (*UpstreamBadRoute*),
“*service*” is empty (*UpstreamBadService*),
no resolver defined to resolve (*UpstreamConfNoResolver*),
upstream “**name**” has no backup (*UpstreamNoBackup*),
upstream “**name**” memory exhausted (*UpstreamOutOfMemory*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: &id004 {}
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: postHttpUpstreamServer400Example
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: postHttpUpstreamServer404Example
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: postHttpUpstreamServer405Example
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: postHttpUpstreamServer409Example
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: postHttpUpstreamServer415Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/http/upstreams/{httpUpstreamName}/servers/{httpUpstreamServerId}:
parameters:
- name: httpUpstreamName
in: path
description: The name of the upstream server group.
required: true
type: string
x-example: example_httpUpstreamName
- name: httpUpstreamServerId
in: path
description: The ID of the server.
required: true
type: string
x-example: example_httpUpstreamServerId
get:
tags:
- HTTP Upstreams
summary: NGINX Return Configuration of a Server in an HTTP Upstream Server Group
description: Returns configuration of a particular server in the HTTP upstream server group.
operationId: getHttpUpstreamPeer
produces:
- application/json
responses:
'200':
description: Success
schema:
$ref: '#/definitions/NginxHTTPUpstreamConfServer'
examples:
application/json:
id: 1
server: 10.0.0.1:8089
weight: 4
max_conns: 0
max_fails: 0
fail_timeout: 10s
slow_start: 10s
route: ''
backup: true
down: true
x-microcks-refs:
- name: getHttpUpstreamPeer200Example
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: getHttpUpstreamPeer400Example
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: *id005
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: getHttpUpstreamPeer404Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
tags:
- HTTP Upstreams
summary: NGINX Modify a Server in an HTTP Upstream Server Group
description: Modifies settings of a particular server in an HTTP upstream server group. Server parameters are specified in the JSON format.
operationId: patchHttpUpstreamPeer
produces:
- application/json
parameters:
- in: body
name: patchHttpUpstreamServer
description: Server parameters, specified in the JSON format. The “*ID*”, “*backup*”, and “*service*” parameters cannot be changed.
required: true
schema:
$ref: '#/definitions/NginxHTTPUpstreamConfServer'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/NginxHTTPUpstreamConfServer'
examples:
application/json:
id: 1
server: 10.0.0.1:8089
weight: 4
max_conns: 0
max_fails: 0
fail_timeout: 10s
slow_start: 10s
route: ''
backup: true
down: true
x-microcks-refs:
- name: patchHttpUpstreamPeer200Example
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*),
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*),
route is too long (*UpstreamBadRoute*),
“*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: patchHttpUpstreamPeer400Example
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: patchHttpUpstreamPeer404Example
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: patchHttpUpstreamPeer405Example
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: patchHttpUpstreamPeer415Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
tags:
- HTTP Upstreams
summary: NGINX Remove a Server from an HTTP Upstream Server Group
description: Removes a server from an HTTP upstream server group.
operationId: deleteHttpUpstreamServer
produces:
- application/json
responses:
'200':
description: Success
schema:
$ref: '#/definitions/NginxHTTPUpstreamConfServerMap'
examples:
application/json:
- id: 0
server: 10.0.0.1:8088
weight: 1
max_conns: 0
max_fails: 0
fail_timeout: 10s
slow_start: 10s
route: ''
backup: false
down: false
- id: 1
server: 10.0.0.1:8089
weight: 4
max_conns: 0
max_fails: 0
fail_timeout: 10s
slow_start: 10s
route: ''
backup: true
down: true
x-microcks-refs:
- name: deleteHttpUpstreamServer200Example
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: deleteHttpUpstreamServer400Example
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: deleteHttpUpstreamServer404Example
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: deleteHttpUpstreamServer405Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
definitions:
NginxHTTPUpstreamConfServerMap:
title: HTTP Upstream Servers
description: An array of HTTP upstream servers for dynamic configuration.
type: array
items:
$ref: '#/definitions/NginxHTTPUpstreamConfServer'
example:
- id: 0
server: 10.0.0.1:8088
weight: 1
max_conns: 0
max_fails: 0
fail_timeout: 10s
slow_start: 10s
route: ''
backup: false
down: false
- id: 1
server: 10.0.0.1:8089
weight: 4
max_conns: 0
max_fails: 0
fail_timeout: 10s
slow_start: 10s
route: ''
backup: true
down: true
NginxHTTPUpstreamPeerMap:
title: HTTP Upstream Servers
description: 'An array of HTTP
<a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream">upstream servers</a>.
'
type: array
items:
$ref: '#/definitions/NginxHTTPUpstreamPeer'
NginxHTTPUpstreamConfServer:
title: HTTP Upstream Server
description: 'Dynamically configurable parameters of an HTTP upstream
<a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</a>:
'
type: object
properties:
id:
type: integer
description: The ID of the HTTP upstream server. The ID is assigned automatically and cannot be changed.
readOnly: true
example: 0
server:
type: string
description: Same as the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">address</a> parameter of the HTTP 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 <a href="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver">resolver</a> directive in the “<code>http</code>” block. See also the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#resolve">resolve</a> parameter of the HTTP upstream server.
example: example-server
service:
type: string
description: Same as the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#service">service</a> parameter of the HTTP upstream server. This parameter cannot be changed.
readOnly: true
example: example-service
weight:
type: integer
des
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nginx/refs/heads/main/openapi/nginx-http-upstreams-api-openapi.yml