openapi: 3.0.3
info:
title: NGINX njs Scripting Connections Method PATCH 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: Method PATCH
paths:
/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
patch:
tags:
- Method PATCH
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: &id001 {}
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: *id001
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: *id001
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: *id001
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: patchHttpUpstreamPeer415Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/http/keyvals/{httpKeyvalZoneName}:
parameters:
- name: httpKeyvalZoneName
in: path
description: The name of an HTTP keyval shared memory zone.
required: true
type: string
x-example: example_httpKeyvalZoneName
patch:
tags:
- Method PATCH
summary: NGINX Modify a Key-Value or Delete a Key
description: Changes the value of the selected key in the key-value pair, deletes a key by setting the key value to <literal>null</literal>, changes expiration time of a key-value pair. If <a href="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</a> of keyval zones in a cluster is enabled, deletes a key only on a target cluster node. Expiration time in milliseconds can be specified for a key-value pair with the *expire* parameter which overrides the [*timeout*](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_timeout) parameter of the <a href="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">keyval_zone</a> directive.
operationId: patchHttpKeyvalZoneKeyValue
produces:
- application/json
parameters:
- in: body
name: httpKeyvalZoneKeyValue
description: A new value for the key is specified in the JSON format.
required: true
schema:
$ref: '#/definitions/NginxHTTPKeyvalZonePostPatch'
responses:
'204':
description: Success
'400':
description: 'Invalid JSON (*KeyvalFormatError*),
key required (*KeyvalFormatError*),
keyval timeout is not enabled (*KeyvalFormatError*),
only one key can be updated (*KeyvalFormatError*),
reading request body failed *BodyReadError*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: &id002 {}
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: patchHttpKeyvalZoneKeyValue400Example
x-microcks-default: true
'404':
description: 'Keyval not found (*KeyvalNotFound*),
keyval key not found (*KeyvalKeyNotFound*),
unknown version (*UnknownVersion*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id002
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: patchHttpKeyvalZoneKeyValue404Example
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: patchHttpKeyvalZoneKeyValue405Example
x-microcks-default: true
'413':
description: Request Entity Too Large
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id002
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: patchHttpKeyvalZoneKeyValue413Example
x-microcks-default: true
'415':
description: JSON error (*JsonError*)
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id002
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: patchHttpKeyvalZoneKeyValue415Example
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
patch:
tags:
- Method PATCH
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: &id003 {}
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: *id003
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: *id003
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: *id003
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: patchStreamUpstreamServer415Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/stream/keyvals/{streamKeyvalZoneName}:
parameters:
- name: streamKeyvalZoneName
in: path
description: The name of a stream keyval shared memory zone.
required: true
type: string
x-example: example_streamKeyvalZoneName
patch:
tags:
- Method PATCH
summary: NGINX Modify a Key-Value or Delete a Key
description: Changes the value of the selected key in the key-value pair, deletes a key by setting the key value to <literal>null</literal>, changes expiration time of a key-value pair. If <a href="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</a> of keyval zones in a cluster is enabled, deletes a key only on a target cluster node. Expiration time is specified in milliseconds with the *expire* parameter which overrides the [*timeout*](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_timeout) parameter of the <a href="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">keyval_zone</a> directive.
operationId: patchStreamKeyvalZoneKeyValue
produces:
- application/json
parameters:
- in: body
name: streamKeyvalZoneKeyValue
description: A new value for the key is specified in the JSON format.
required: true
schema:
$ref: '#/definitions/NginxStreamKeyvalZonePostPatch'
responses:
'204':
description: Success
'400':
description: 'Invalid JSON (*KeyvalFormatError*),
key required (*KeyvalFormatError*),
keyval timeout is not enabled (*KeyvalFormatError*),
only one key can be updated (*KeyvalFormatError*),
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: patchStreamKeyvalZoneKeyValue400Example
x-microcks-default: true
'404':
description: 'Keyval not found (*KeyvalNotFound*),
keyval key not found (*KeyvalKeyNotFound*),
unknown version (*UnknownVersion*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id004
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: patchStreamKeyvalZoneKeyValue404Example
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: patchStreamKeyvalZoneKeyValue405Example
x-microcks-default: true
'413':
description: Request Entity Too Large
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id004
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: patchStreamKeyvalZoneKeyValue413Example
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: patchStreamKeyvalZoneKeyValue415Example
x-microcks-default: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
definitions:
NginxStreamKeyvalZonePostPatch:
title: Stream Keyval Shared Memory Zone
description: 'Contents of a stream keyval shared memory zone
when using the POST or PATCH methods.
'
type: object
example:
key1: value1
key2: value2
key3:
value: value3
expire: 30000
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
description: Same as the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#weight">weight</a> parameter of the HTTP upstream server.
example: 0
max_conns:
type: integer
description: Same as the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns">max_conns</a> parameter of the HTTP upstream server.
example: 0
max_fails:
type: integer
description: Same as the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails">max_fails</a> parameter of the HTTP upstream server.
example: 0
fail_timeout:
type: string
description: Same as the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#fail_timeout">fail_timeout</a> parameter of the HTTP upstream server.
example: example-fail_timeout
slow_start:
type: string
description: Same as the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#slow_start">slow_start</a> parameter of the HTTP upstream server.
example: example-slow_start
route:
type: string
description: Same as the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#route">route</a> parameter of the HTTP upstream server.
example: example-route
backup:
type: boolean
description: When <code>true</code>, adds a <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#backup">backup</a> server. This parameter cannot be changed.
readOnly: true
example: false
down:
type: boolean
description: Same as the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#down">down</a> parameter of the HTTP upstream server.
example: false
drain:
type: boolean
description: Same as the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#drain">drain</a> parameter of the HTTP upstream server.
example: false
parent:
type: string
description: Parent server ID of the resolved server. The ID is assigned automatically and cannot be changed.
readOnly: true
example: example-parent
host:
type: string
description: Hostname of the resolved server. The hostname is assigned automatically and cannot be changed.
readOnly: true
example: example-host
example:
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
NginxStreamUpstreamConfServer:
title: Stream Upstream Server
description: 'Dynamically configurable parameters of a stream upstream
<a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">server</a>:
'
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
example: 0
server:
type: string
description: Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#server">address</a> 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 <a href="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#resolver">resolver</a> directive in the “<code>stream</code>” block. See also the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#resolve">resolve</a> parameter of the stream upstream server.
example: example-server
service:
type: string
description: Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#service">service</a> parameter of the stream upstream server. This parameter cannot be changed.
readOnly: true
example: example-service
weight:
type: integer
description: Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#weight">weight</a> parameter of the stream upstream server.
example: 0
max_conns:
type: integer
description: Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_conns">max_conns</a> parameter of the stream upstream server.
example: 0
max_fails:
type: integer
description: Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_fails">max_fails</a> parameter of the stream upstream server.
example: 0
fail_timeout:
type: string
description: Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#fail_timeout">fail_timeout</a> parameter of the stream upstream server.
example: example-fail_timeout
slow_start:
type: string
description: Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#slow_start">slow_start</a> parameter of the stream upstream server.
example: example-slow_start
backup:
type: boolean
description: When <code>true</code>, adds a <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#backup">backup</a> server. This parameter cannot be changed.
readOnly: true
example: false
down:
type: boolean
description: Same as the <a href="https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#down">down</a> parameter of the stream upstream server.
example: false
parent:
type: string
description: Parent server ID of the resolved server. The ID is assigned automatically and cannot be changed.
readOnly: true
example: example-parent
host:
type: string
description: Hostname of the resolved server. The hostname is assigned automatically and cannot be changed.
readOnly: true
example: example-host
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
NginxHTTPKeyvalZonePostPatch:
title: HTTP Keyval Shared Memory Zone
description: 'Contents of an HTTP keyval shared memory zone
when using the POST or PATCH methods.
'
type: object
example:
key1: value1
key2: value2
key3:
value: value3
expire: 30000
NginxError:
title: Error
description: 'nginx error object.
'
type: object
properties:
error:
type: object
properties:
status:
type: integer
description: HTTP error code.
example: 200
text:
type: string
description: Error description.
example: example-text
code:
type: string
description: Internal nginx error code.
example: 200
example: {}
request_id:
type: string
description: The ID of the request, equals the value of the <a href="https://nginx.org/en/docs/http/ngx_http_core_module.html#var_request_id">$request_id</a> variable.
example: example-request_id
href:
type: string
description: Link to reference documentation.
example: example-href
externalDocs:
description: NGINX njs Reference
url: https://nginx.org/en/docs/njs/reference.html