openapi: 3.0.3
info:
title: NGINX njs Scripting Connections Method POST 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 POST
paths:
/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
post:
tags:
- Method POST
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: &id001 {}
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: *id001
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: *id001
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: *id001
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: *id001
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/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
post:
tags:
- Method POST
summary: NGINX Add a Key-Value Pair to the HTTP Keyval Zone
description: Adds a new key-value pair to the HTTP keyval shared memory [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). Several key-value pairs can be entered if the HTTP keyval shared memory zone is empty.
operationId: postHttpKeyvalZoneData
produces:
- application/json
parameters:
- in: body
name: Key-value
description: A key-value pair is specified in the JSON format. Several key-value pairs can be entered if the HTTP keyval shared memory zone is empty. 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.
required: true
schema:
$ref: '#/definitions/NginxHTTPKeyvalZonePostPatch'
responses:
'201':
description: Created
'400':
description: 'Invalid JSON (*KeyvalFormatError*),
invalid key format (*KeyvalFormatError*),
key required (*KeyvalFormatError*),
keyval timeout is not enabled (*KeyvalFormatError*),
only one key can be added (*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: postHttpKeyvalZoneData400Example
x-microcks-default: true
'404':
description: 'Keyval not found (*KeyvalNotFound*),
unknown version (*UnknownVersion*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id002
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: postHttpKeyvalZoneData404Example
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: postHttpKeyvalZoneData405Example
x-microcks-default: true
'409':
description: 'Entry exists (*EntryExists*),
key already exists (*KeyvalKeyExists*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id002
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: postHttpKeyvalZoneData409Example
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: postHttpKeyvalZoneData413Example
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: postHttpKeyvalZoneData415Example
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
post:
tags:
- Method POST
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: &id003 {}
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: *id003
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: *id003
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: *id003
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: *id003
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/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
post:
tags:
- Method POST
summary: NGINX Add a Key-Value Pair to the Stream Keyval Zone
description: Adds a new key-value pair to the stream keyval shared memory [zone](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone). Several key-value pairs can be entered if the stream keyval shared memory zone is empty.
operationId: postStreamKeyvalZoneData
produces:
- application/json
parameters:
- in: body
name: Key-value
description: A key-value pair is specified in the JSON format. Several key-value pairs can be entered if the stream keyval shared memory zone is empty. 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/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.
required: true
schema:
$ref: '#/definitions/NginxStreamKeyvalZonePostPatch'
responses:
'201':
description: Created
'400':
description: 'Invalid JSON (*KeyvalFormatError*),
invalid key format (*KeyvalFormatError*),
key required (*KeyvalFormatError*),
keyval timeout is not enabled (*KeyvalFormatError*),
only one key can be added (*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: postStreamKeyvalZoneData400Example
x-microcks-default: true
'404':
description: 'Keyval not found (*KeyvalNotFound*),
unknown version (*UnknownVersion*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id004
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: postStreamKeyvalZoneData404Example
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: postStreamKeyvalZoneData405Example
x-microcks-default: true
'409':
description: 'Entry exists (*EntryExists*),
key already exists (*KeyvalKeyExists*)
'
schema:
$ref: '#/definitions/NginxError'
examples:
application/json:
error: *id004
request_id: example-request_id
href: example-href
x-microcks-refs:
- name: postStreamKeyvalZoneData409Example
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: postStreamKeyvalZoneData413Example
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: postStreamKeyvalZoneData415Example
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