Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_api_module.xml @ 2866:8bd6f772005f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated docs for the upcoming NGINX Plus release.
author Yaroslav Zhuravlev <yar@nginx.com>
date Sat, 25 Jun 2022 18:55:17 +0100
parents 9dd8c203a54a
children 3a2d342533fb
comparison
equal deleted inserted replaced
2865:0d355d154181 2866:8bd6f772005f
108 </example> 108 </example>
109 All API requests include 109 All API requests include
110 a supported API <link id="api_version">version</link> in the URI. 110 a supported API <link id="api_version">version</link> in the URI.
111 Examples of API requests with this configuration: 111 Examples of API requests with this configuration:
112 <example> 112 <example>
113 http://127.0.0.1/api/7/ 113 http://127.0.0.1/api/8/
114 http://127.0.0.1/api/7/nginx 114 http://127.0.0.1/api/8/nginx
115 http://127.0.0.1/api/7/connections 115 http://127.0.0.1/api/8/connections
116 http://127.0.0.1/api/7/http/requests 116 http://127.0.0.1/api/8/http/requests
117 http://127.0.0.1/api/7/http/server_zones/server_backend 117 http://127.0.0.1/api/8/http/server_zones/server_backend
118 http://127.0.0.1/api/7/http/caches/cache_backend 118 http://127.0.0.1/api/8/http/caches/cache_backend
119 http://127.0.0.1/api/7/http/upstreams/backend 119 http://127.0.0.1/api/8/http/upstreams/backend
120 http://127.0.0.1/api/7/http/upstreams/backend/servers/ 120 http://127.0.0.1/api/8/http/upstreams/backend/servers/
121 http://127.0.0.1/api/7/http/upstreams/backend/servers/1 121 http://127.0.0.1/api/8/http/upstreams/backend/servers/1
122 http://127.0.0.1/api/7/http/keyvals/one?key=arg1 122 http://127.0.0.1/api/8/http/keyvals/one?key=arg1
123 http://127.0.0.1/api/7/stream/ 123 http://127.0.0.1/api/8/stream/
124 http://127.0.0.1/api/7/stream/server_zones/server_backend 124 http://127.0.0.1/api/8/stream/server_zones/server_backend
125 http://127.0.0.1/api/7/stream/upstreams/ 125 http://127.0.0.1/api/8/stream/upstreams/
126 http://127.0.0.1/api/7/stream/upstreams/backend 126 http://127.0.0.1/api/8/stream/upstreams/backend
127 http://127.0.0.1/api/7/stream/upstreams/backend/servers/1 127 http://127.0.0.1/api/8/stream/upstreams/backend/servers/1
128 </example> 128 </example>
129 </para> 129 </para>
130 130
131 </section> 131 </section>
132 132
153 153
154 <para id="api_version"> 154 <para id="api_version">
155 All API requests should contain a supported API version in the URI. 155 All API requests should contain a supported API version in the URI.
156 If the request URI equals the location prefix, 156 If the request URI equals the location prefix,
157 the list of supported API versions is returned. 157 the list of supported API versions is returned.
158 The current API version is “<literal>7</literal>”. 158 The current API version is “<literal>8</literal>”.
159 </para> 159 </para>
160 160
161 <para> 161 <para>
162 The optional “<literal>fields</literal>” argument in the request line 162 The optional “<literal>fields</literal>” argument in the request line
163 specifies which fields of the requested objects will be output: 163 specifies which fields of the requested objects will be output:
164 <example> 164 <example>
165 http://127.0.0.1/api/7/nginx?fields=version,build 165 http://127.0.0.1/api/8/nginx?fields=version,build
166 </example> 166 </example>
167 </para> 167 </para>
168 168
169 </directive> 169 </directive>
170 170
206 206
207 <para> 207 <para>
208 <list type="bullet"> 208 <list type="bullet">
209 209
210 <listitem> 210 <listitem>
211 The <literal>ssl</literal> data
212 for each HTTP
213 <link id="def_nginx_http_upstream">upstream</link>,
214 <link id="def_nginx_http_server_zone">server zone</link>,
215 and stream
216 <link id="def_nginx_stream_upstream">upstream</link>,
217 <link id="def_nginx_stream_server_zone">server zone</link>,
218 were added in <link id="api_version">version</link> 8.
219 </listitem>
220
221 <listitem>
211 The <literal>codes</literal> data 222 The <literal>codes</literal> data
212 in <literal>responses</literal> for each HTTP 223 in <literal>responses</literal> for each HTTP
213 <link id="def_nginx_http_upstream">upstream</link>, 224 <link id="def_nginx_http_upstream">upstream</link>,
214 <link id="def_nginx_http_server_zone">server zone</link>, and 225 <link id="def_nginx_http_server_zone">server zone</link>, and
215 <link id="def_nginx_http_location_zone">location zone</link> 226 <link id="def_nginx_http_location_zone">location zone</link>
595 unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> 606 unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
596 </list> 607 </list>
597 </listitem> 608 </listitem>
598 <listitem id="deleteHttpServerZoneStat"> 609 <listitem id="deleteHttpServerZoneStat">
599 <literal>DELETE</literal> - Reset statistics for an HTTP server zone 610 <literal>DELETE</literal> - Reset statistics for an HTTP server zone
600 <para>Resets statistics of accepted and discarded requests, responses, received and sent bytes in a particular HTTP server zone.</para> 611 <para>Resets statistics of accepted and discarded requests, responses, received and sent bytes, counters of SSL handshakes and session reuses in a particular HTTP server zone.</para>
601 <para> 612 <para>
602 Possible responses: 613 Possible responses:
603 </para> 614 </para>
604 <list type="bullet"> 615 <list type="bullet">
605 <listitem>204 - Success</listitem> 616 <listitem>204 - Success</listitem>
1382 unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> 1393 unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1383 </list> 1394 </list>
1384 </listitem> 1395 </listitem>
1385 <listitem id="deleteStreamServerZoneStat"> 1396 <listitem id="deleteStreamServerZoneStat">
1386 <literal>DELETE</literal> - Reset statistics for a stream server zone 1397 <literal>DELETE</literal> - Reset statistics for a stream server zone
1387 <para>Resets statistics of accepted and discarded connections, sessions, received and sent bytes in a particular stream server zone.</para> 1398 <para>Resets statistics of accepted and discarded connections, sessions, received and sent bytes, counters of SSL handshakes and session reuses in a particular stream server zone.</para>
1388 <para> 1399 <para>
1389 Possible responses: 1400 Possible responses:
1390 </para> 1401 </para>
1391 <list type="bullet"> 1402 <list type="bullet">
1392 <listitem>204 - Success</listitem> 1403 <listitem>204 - Success</listitem>
2053 </list> 2064 </list>
2054 <para>Example:</para> 2065 <para>Example:</para>
2055 <example> 2066 <example>
2056 { 2067 {
2057 "nginx" : { 2068 "nginx" : {
2058 "version" : "1.17.3", 2069 "version" : "1.21.6",
2059 "build" : "nginx-plus-r19", 2070 "build" : "nginx-plus-r27",
2060 "address" : "206.251.255.64", 2071 "address" : "206.251.255.64",
2061 "generation" : 6, 2072 "generation" : 6,
2062 "load_timestamp" : "2019-10-01T11:15:44.467Z", 2073 "load_timestamp" : "2022-06-28T11:15:44.467Z",
2063 "timestamp" : "2019-10-01T09:26:07.305Z", 2074 "timestamp" : "2022-06-28T09:26:07.305Z",
2064 "pid" : 32212, 2075 "pid" : 32212,
2065 "ppid" : 32210 2076 "ppid" : 32210
2066 } 2077 }
2067 }</example> 2078 }</example>
2068 </listitem> 2079 </listitem>
2360 <literal>sent</literal> (<literal>integer</literal>) 2371 <literal>sent</literal> (<literal>integer</literal>)
2361 </tag-name> 2372 </tag-name>
2362 <tag-desc> 2373 <tag-desc>
2363 The total number of bytes sent to clients. 2374 The total number of bytes sent to clients.
2364 </tag-desc> 2375 </tag-desc>
2376 <tag-name>
2377 <literal>ssl</literal></tag-name>
2378 <tag-desc>
2379 <list type="tag">
2380 <tag-name>
2381 <literal>handshakes</literal> (<literal>integer</literal>)
2382 </tag-name>
2383 <tag-desc>
2384 The total number of successful SSL handshakes.
2385 </tag-desc>
2386 <tag-name>
2387 <literal>handshakes_failed</literal> (<literal>integer</literal>)
2388 </tag-name>
2389 <tag-desc>
2390 The total number of failed SSL handshakes.
2391 </tag-desc>
2392 <tag-name>
2393 <literal>session_reuses</literal> (<literal>integer</literal>)
2394 </tag-name>
2395 <tag-desc>
2396 The total number of session reuses during SSL handshake.
2397 </tag-desc>
2398 </list>
2399 </tag-desc>
2365 </list> 2400 </list>
2366 <para>Example:</para> 2401 <para>Example:</para>
2367 <example> 2402 <example>
2368 { 2403 {
2369 "processing" : 1, 2404 "processing" : 1,
2382 }, 2417 },
2383 "total" : 705177 2418 "total" : 705177
2384 }, 2419 },
2385 "discarded" : 1513, 2420 "discarded" : 1513,
2386 "received" : 172711587, 2421 "received" : 172711587,
2387 "sent" : 19415530115 2422 "sent" : 19415530115,
2423 "ssl" : {
2424 "handshakes" : 104303,
2425 "handshakes_failed" : 1421,
2426 "session_reuses" : 54645
2427 }
2388 }</example> 2428 }</example>
2389 </listitem> 2429 </listitem>
2390 <listitem id="def_nginx_http_location_zone"> 2430 <listitem id="def_nginx_http_location_zone">
2391 <para>HTTP Location Zone:</para> 2431 <para>HTTP Location Zone:</para>
2392 <list type="tag"> 2432 <list type="tag">
2844 </tag-name> 2884 </tag-name>
2845 <tag-desc> 2885 <tag-desc>
2846 The current number of active connections. 2886 The current number of active connections.
2847 </tag-desc> 2887 </tag-desc>
2848 <tag-name> 2888 <tag-name>
2889 <literal>ssl</literal></tag-name>
2890 <tag-desc>
2891 <list type="tag">
2892 <tag-name>
2893 <literal>handshakes</literal> (<literal>integer</literal>)
2894 </tag-name>
2895 <tag-desc>
2896 The total number of successful SSL handshakes.
2897 </tag-desc>
2898 <tag-name>
2899 <literal>handshakes_failed</literal> (<literal>integer</literal>)
2900 </tag-name>
2901 <tag-desc>
2902 The total number of failed SSL handshakes.
2903 </tag-desc>
2904 <tag-name>
2905 <literal>session_reuses</literal> (<literal>integer</literal>)
2906 </tag-name>
2907 <tag-desc>
2908 The total number of session reuses during SSL handshake.
2909 </tag-desc>
2910 </list>
2911 </tag-desc>
2912 <tag-name>
2849 <literal>max_conns</literal> (<literal>integer</literal>) 2913 <literal>max_conns</literal> (<literal>integer</literal>)
2850 </tag-name> 2914 </tag-name>
2851 <tag-desc> 2915 <tag-desc>
2852 The <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns">max_conns</link> limit for the server. 2916 The <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns">max_conns</link> limit for the server.
2853 </tag-desc> 2917 </tag-desc>
3051 "name" : "10.0.0.1:8088", 3115 "name" : "10.0.0.1:8088",
3052 "backup" : false, 3116 "backup" : false,
3053 "weight" : 5, 3117 "weight" : 5,
3054 "state" : "up", 3118 "state" : "up",
3055 "active" : 0, 3119 "active" : 0,
3120 "ssl" : {
3121 "handshakes" : 620311,
3122 "handshakes_failed" : 3432,
3123 "session_reuses" : 36442
3124 },
3056 "max_conns" : 20, 3125 "max_conns" : 20,
3057 "requests" : 667231, 3126 "requests" : 667231,
3058 "header_time" : 20, 3127 "header_time" : 20,
3059 "response_time" : 36, 3128 "response_time" : 36,
3060 "responses" : { 3129 "responses" : {
3079 "fails" : 0, 3148 "fails" : 0,
3080 "unhealthy" : 0, 3149 "unhealthy" : 0,
3081 "last_passed" : true 3150 "last_passed" : true
3082 }, 3151 },
3083 "downtime" : 0, 3152 "downtime" : 0,
3084 "downstart" : "2019-10-01T11:09:21.602Z", 3153 "downstart" : "2022-06-28T11:09:21.602Z",
3085 "selected" : "2019-10-01T15:01:25.000Z" 3154 "selected" : "2022-06-28T15:01:25.000Z"
3086 }, 3155 },
3087 { 3156 {
3088 "id" : 1, 3157 "id" : 1,
3089 "server" : "10.0.0.1:8089", 3158 "server" : "10.0.0.1:8089",
3090 "name" : "10.0.0.1:8089", 3159 "name" : "10.0.0.1:8089",
3113 "fails" : 26284, 3182 "fails" : 26284,
3114 "unhealthy" : 1, 3183 "unhealthy" : 1,
3115 "last_passed" : false 3184 "last_passed" : false
3116 }, 3185 },
3117 "downtime" : 262925617, 3186 "downtime" : 262925617,
3118 "downstart" : "2019-10-01T11:09:21.602Z", 3187 "downstart" : "2022-06-28T11:09:21.602Z",
3119 "selected" : "2019-10-01T15:01:25.000Z" 3188 "selected" : "2022-06-28T15:01:25.000Z"
3120 } 3189 }
3121 ], 3190 ],
3122 "keepalive" : 0, 3191 "keepalive" : 0,
3123 "zombies" : 0, 3192 "zombies" : 0,
3124 "zone" : "upstream_backend" 3193 "zone" : "upstream_backend"
3315 <literal>sent</literal> (<literal>integer</literal>) 3384 <literal>sent</literal> (<literal>integer</literal>)
3316 </tag-name> 3385 </tag-name>
3317 <tag-desc> 3386 <tag-desc>
3318 The total number of bytes sent to clients. 3387 The total number of bytes sent to clients.
3319 </tag-desc> 3388 </tag-desc>
3389 <tag-name>
3390 <literal>ssl</literal></tag-name>
3391 <tag-desc>
3392 <list type="tag">
3393 <tag-name>
3394 <literal>handshakes</literal> (<literal>integer</literal>)
3395 </tag-name>
3396 <tag-desc>
3397 The total number of successful SSL handshakes.
3398 </tag-desc>
3399 <tag-name>
3400 <literal>handshakes_failed</literal> (<literal>integer</literal>)
3401 </tag-name>
3402 <tag-desc>
3403 The total number of failed SSL handshakes.
3404 </tag-desc>
3405 <tag-name>
3406 <literal>session_reuses</literal> (<literal>integer</literal>)
3407 </tag-name>
3408 <tag-desc>
3409 The total number of session reuses during SSL handshake.
3410 </tag-desc>
3411 </list>
3412 </tag-desc>
3320 </list> 3413 </list>
3321 <para>Example:</para> 3414 <para>Example:</para>
3322 <example> 3415 <example>
3323 { 3416 {
3324 "dns" : { 3417 "dns" : {
3330 "5xx" : 0, 3423 "5xx" : 0,
3331 "total" : 155569 3424 "total" : 155569
3332 }, 3425 },
3333 "discarded" : 0, 3426 "discarded" : 0,
3334 "received" : 4200363, 3427 "received" : 4200363,
3335 "sent" : 20489184 3428 "sent" : 20489184,
3429 "ssl" : {
3430 "handshakes" : 76455,
3431 "handshakes_failed" : 432,
3432 "session_reuses" : 28770
3433 }
3336 } 3434 }
3337 }</example> 3435 }</example>
3338 </listitem> 3436 </listitem>
3339 <listitem id="def_nginx_stream_limit_conn_zone"> 3437 <listitem id="def_nginx_stream_limit_conn_zone">
3340 <para>Stream Connections Limiting:</para> 3438 <para>Stream Connections Limiting:</para>
3418 <tag-name> 3516 <tag-name>
3419 <literal>active</literal> (<literal>integer</literal>) 3517 <literal>active</literal> (<literal>integer</literal>)
3420 </tag-name> 3518 </tag-name>
3421 <tag-desc> 3519 <tag-desc>
3422 The current number of connections. 3520 The current number of connections.
3521 </tag-desc>
3522 <tag-name>
3523 <literal>ssl</literal></tag-name>
3524 <tag-desc>
3525 <list type="tag">
3526 <tag-name>
3527 <literal>handshakes</literal> (<literal>integer</literal>)
3528 </tag-name>
3529 <tag-desc>
3530 The total number of successful SSL handshakes.
3531 </tag-desc>
3532 <tag-name>
3533 <literal>handshakes_failed</literal> (<literal>integer</literal>)
3534 </tag-name>
3535 <tag-desc>
3536 The total number of failed SSL handshakes.
3537 </tag-desc>
3538 <tag-name>
3539 <literal>session_reuses</literal> (<literal>integer</literal>)
3540 </tag-name>
3541 <tag-desc>
3542 The total number of session reuses during SSL handshake.
3543 </tag-desc>
3544 </list>
3423 </tag-desc> 3545 </tag-desc>
3424 <tag-name> 3546 <tag-name>
3425 <literal>max_conns</literal> (<literal>integer</literal>) 3547 <literal>max_conns</literal> (<literal>integer</literal>)
3426 </tag-name> 3548 </tag-name>
3427 <tag-desc> 3549 <tag-desc>
3549 "name" : "10.0.0.1:12347", 3671 "name" : "10.0.0.1:12347",
3550 "backup" : false, 3672 "backup" : false,
3551 "weight" : 5, 3673 "weight" : 5,
3552 "state" : "up", 3674 "state" : "up",
3553 "active" : 0, 3675 "active" : 0,
3676 "ssl" : {
3677 "handshakes" : 200,
3678 "handshakes_failed" : 4,
3679 "session_reuses" : 189
3680 },
3554 "max_conns" : 50, 3681 "max_conns" : 50,
3555 "connections" : 667231, 3682 "connections" : 667231,
3556 "sent" : 251946292, 3683 "sent" : 251946292,
3557 "received" : 19222475454, 3684 "received" : 19222475454,
3558 "fails" : 0, 3685 "fails" : 0,
3562 "fails" : 0, 3689 "fails" : 0,
3563 "unhealthy" : 0, 3690 "unhealthy" : 0,
3564 "last_passed" : true 3691 "last_passed" : true
3565 }, 3692 },
3566 "downtime" : 0, 3693 "downtime" : 0,
3567 "downstart" : "2019-10-01T11:09:21.602Z", 3694 "downstart" : "2022-06-28T11:09:21.602Z",
3568 "selected" : "2019-10-01T15:01:25.000Z" 3695 "selected" : "2022-06-28T15:01:25.000Z"
3569 }, 3696 },
3570 { 3697 {
3571 "id" : 1, 3698 "id" : 1,
3572 "server" : "10.0.0.1:12348", 3699 "server" : "10.0.0.1:12348",
3573 "name" : "10.0.0.1:12348", 3700 "name" : "10.0.0.1:12348",
3586 "fails" : 26284, 3713 "fails" : 26284,
3587 "unhealthy" : 1, 3714 "unhealthy" : 1,
3588 "last_passed" : false 3715 "last_passed" : false
3589 }, 3716 },
3590 "downtime" : 262925617, 3717 "downtime" : 262925617,
3591 "downstart" : "2019-10-01T11:09:21.602Z", 3718 "downstart" : "2022-06-28T11:09:21.602Z",
3592 "selected" : "2019-10-01T15:01:25.000Z" 3719 "selected" : "2022-06-28T15:01:25.000Z"
3593 } 3720 }
3594 ], 3721 ],
3595 "zombies" : 0, 3722 "zombies" : 0,
3596 "zone" : "dns" 3723 "zone" : "dns"
3597 } 3724 }