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
        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
  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
  NginxHTTPUpstreamMap:
    title: HTTP Upstreams
    description: 'Status information of all HTTP

      <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone">dynamically configurable</a>

      <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream">groups</a>.

      '
    type: object
    additionalProperties:
      $ref: '#/definitions/NginxHTTPUpstream'
    example:
      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
  NginxHTTPUpstreamPeer:
    title: HTTP Upstream Server
    type: object
    properties:
      id:
        type: integer
        description: The ID of the server.
        readOnly: true
        example: 0
      server:
        type: string
        description: An  <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">address</a> of the server.
        example: example-server
      service:
        type: string
        description: The <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#service">service</a> parameter value of the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</a> directive.
        example: example-service
      name:
        type: string
        description: The name of the server specified in the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">server</a> directive.
        readOnly: true
        example: my_shared_zone
      backup:
        type: boolean
        description: A boolean value indicating whether the server is a <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#backup">backup</a> server.
        example: false
      weight:
        type: integer
        description: <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#weight">Weight</a> of the server.
        example: 0
      state:
        type: string
        enum:
        - up
        - draining
        - down
        - unavail
        - checking
        - unhealthy
        description: Current state, which may be one of “<code>up</code>”, “<code>draining</code>”, “<code>down</code>”, “<code>unavail</code>”, “<code>checking</code>”, and “<code>unhealthy</code>”.
        example: example-state
      active:
        type: integer
        description: The current number of active connections.
        readOnly: true
        example: 5
      ssl:
        type: object
        readOnly: true
        properties:
          handshakes:
            type: integer
            description: The total number of successful SSL handshakes.
            readOnly: true
            example: 79572
          handshakes_failed:
            type: integer
            description: The total number of failed SSL handshakes.
            readOnly: true
            example: 21025
          session_reuses:
            type: integer
            description: The total number of session reuses during SSL handshake.
            readOnly: true
            example: 15762
          no_common_protocol:
            type: integer
            description: The number of SSL handshakes failed because of no common protocol.
            example: 4
          handshake_timeout:
            type: integer
            description: The number of SSL handshakes failed because of a timeout.
            example: 0
          peer_rejected_cert:
            type: integer
            description: The number of failed SSL handshakes when nginx presented the certificate to the upstream server but it was rejected with a corresponding alert message.
            example: 0
          verify_failures:
            type: object
            description: SSL certificate verification errors
            properties:
              expired_cert:
                type: integer
                description: An expired or not yet valid certificate was presented by an upstream server.
                example: 2
              revoked_cert:
                type: integer
                description: A revoked certificate was presented by an upstream server.
                example: 1
              hostname_mismatch:
                type: integer
                description: Server's certificate doesn't match the hostname.
                example: 2
              other:
                type: integer
                description: Other SSL certificate verification errors.
                example: 1
            example: {}
        example: {}
      max_conns:
        type: integer
        description: The <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns">max_conns</a> limit for the server.
        example: 0
      requests:
        type: integer
        description: The total number of client requests forwarded to this server.
        readOnly: true
        example: 31070465
      responses:
        type: object
        readOnly: true
        properties:
          1xx:
            type: integer
            description: The number of responses with “<code>1xx</code>” status codes.
            readOnly: true
            example: 0
          2xx:
            type: integer
            description: The number of responses with “<code>2xx</code>” status codes.
            readOnly: true
            example: 0
          3xx:
            type: integer
            description: The number of responses with “<code>3xx</code>” status codes.
            readOnly: true
            example: 0
          4xx:
            type: integer
            description: The number of responses with “<code>4xx</code>” status codes.
            readOnly: true
            example: 0
          5xx:
            type: integer
            description: The number of responses with “<code>5xx</code>” status codes.
            readOnly: true
            example: 0
          codes:
            type: object
            description: The number of responses per each status code.
            readOnly: true
            properties:
              codeNumber:
                type: integer
                description: The number of responses with this particular status code.
                readOnly: true
                example: 0
            example: {}
          total:
            type: integer
            description: The total number of responses obtained from this server.
            readOnly: true
            example: 98765
        example: 1234567
      sent:
        type: integer
        description: The total number of bytes sent to this server.
        readOnly: true
        example: 20183175459
      received:
        type: integer
        description: The total number of bytes received from this server.
        readOnly: true
        example: 180157219
      fails:
        type: integer
        description: The total number of unsuccessful attempts to communicate with the server.
        readOnly: true
        example: 0
      unavail:
        type: integer
        description: How many times the server became unavailable for client requests (state “<code>unavail</code>”) due to the number of unsuccessful attempts reaching the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails">max_fails</a> threshold.
        readOnly: true
        example: 0
      health_checks:
        type: object
        readOnly: true
        properties:
          checks:
            type: integer
            description: The total number of <a href="https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#health_check">health check</a> requests made.
            example: 0
          fails:
            type: integer
            description: The number of failed health checks.
            example: 0
          unhealthy:
            type: integer
            description: How many times the server became unhealthy (state “<code>unhealthy</code>”).
            example: 0
          last_passed:
            type: boolean
            description: Boolean indicating if the last health check request was successful and passed <a href="https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#match">tests</a>.
            example: false
        example: 0
      downtime:
        type: integer
        readOnly: true
        description: Total time the server was in the “<code>unavail</code>”, “<code>checking</code>”, and “<code>unhealthy</code>” states.
        example: 0
      downstart:
        type: string
        format: date-time
        readOnly: true
        description: The time when the server became “<code>unavail</code>”, “<code>checking</code>”, or “<code>unhealthy</code>”, in the ISO 8601 format with millisecond resolution.
        example: '2026-04-21T10:30:00.000Z'
      selected:
        type: string
        format: date-time
        readOnly: true
        description: The time when the server was last selected to process a request, in the ISO 8601 format with millisecond resolution.
        example: '2026-04-21T10:30:00.000Z'
      header_time:
        type: integer
        readOnly: true
        description: The average time to get the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_header_time">response header</a> from the server.
        example: 0
      response_time:
        type: integer
        readOnly: true
        description: The average time to get the <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_response_time">full response</a> from the server.
        example: 0
  NginxHTTPUpstream:
    title: HTTP Upstream
    type: object
    properties:
      peers:
        $ref: '#/definitions/NginxHTTPUpstreamPeerMap'
      keepalive:
        type: integer
        description: The current number of idle <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive">keepalive</a> connections.
        example: 0
      zombies:
        type: integer
        description: The current number of servers removed from the group but still processing active client requests.
        example: 0
      zone:
        type: string
        description: The name of the shared memory <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone">zone</a> that keeps the group’s configuration and run-time state.
        example: example-zone
      queue:
        type: object
        description: 'For the requests <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#queue">queue</a>, the following data are provided:

          '
        properties:
          size:
            type: integer
            description: The current number of requests in the queue.
            example: 0
          max_size:
            type: integer
            description: The maximum number of requests that can be in the queue at the same time.
            example: 0
          overflows:
            type: integer
            description: The total number of requests rejected due to the queue overflow.
            example: 0
        example: {}
    example:
      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
externalDocs:
  description: NGINX njs Reference
  url: https://nginx.org/en/docs/njs/reference.html