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