Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_api_module.xml @ 2469:98fd810c13e0

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 Ruslan Ermilov <ru@nginx.com>
date Mon, 02 Dec 2019 13:23:05 +0300
parents 12716b241230
children 407147d8020f
comparison
equal deleted inserted replaced
2468:409e1f755037 2469:98fd810c13e0
99 </example> 99 </example>
100 All API requests include 100 All API requests include
101 a supported API <link id="api_version">version</link> in the URI. 101 a supported API <link id="api_version">version</link> in the URI.
102 Examples of API requests with this configuration: 102 Examples of API requests with this configuration:
103 <example> 103 <example>
104 http://127.0.0.1/api/5/ 104 http://127.0.0.1/api/6/
105 http://127.0.0.1/api/5/nginx 105 http://127.0.0.1/api/6/nginx
106 http://127.0.0.1/api/5/connections 106 http://127.0.0.1/api/6/connections
107 http://127.0.0.1/api/5/http/requests 107 http://127.0.0.1/api/6/http/requests
108 http://127.0.0.1/api/5/http/server_zones/server_backend 108 http://127.0.0.1/api/6/http/server_zones/server_backend
109 http://127.0.0.1/api/5/http/caches/cache_backend 109 http://127.0.0.1/api/6/http/caches/cache_backend
110 http://127.0.0.1/api/5/http/upstreams/backend 110 http://127.0.0.1/api/6/http/upstreams/backend
111 http://127.0.0.1/api/5/http/upstreams/backend/servers/ 111 http://127.0.0.1/api/6/http/upstreams/backend/servers/
112 http://127.0.0.1/api/5/http/upstreams/backend/servers/1 112 http://127.0.0.1/api/6/http/upstreams/backend/servers/1
113 http://127.0.0.1/api/5/http/keyvals/one?key=arg1 113 http://127.0.0.1/api/6/http/keyvals/one?key=arg1
114 http://127.0.0.1/api/5/stream/ 114 http://127.0.0.1/api/6/stream/
115 http://127.0.0.1/api/5/stream/server_zones/server_backend 115 http://127.0.0.1/api/6/stream/server_zones/server_backend
116 http://127.0.0.1/api/5/stream/upstreams/ 116 http://127.0.0.1/api/6/stream/upstreams/
117 http://127.0.0.1/api/5/stream/upstreams/backend 117 http://127.0.0.1/api/6/stream/upstreams/backend
118 http://127.0.0.1/api/5/stream/upstreams/backend/servers/1 118 http://127.0.0.1/api/6/stream/upstreams/backend/servers/1
119 </example> 119 </example>
120 </para> 120 </para>
121 121
122 </section> 122 </section>
123 123
144 144
145 <para id="api_version"> 145 <para id="api_version">
146 All API requests should contain a supported API version in the URI. 146 All API requests should contain a supported API version in the URI.
147 If the request URI equals the location prefix, 147 If the request URI equals the location prefix,
148 the list of supported API versions is returned. 148 the list of supported API versions is returned.
149 The current API version is “<literal>5</literal>”. 149 The current API version is “<literal>6</literal>”.
150 </para> 150 </para>
151 151
152 <para> 152 <para>
153 The optional “<literal>fields</literal>” argument in the request line 153 The optional “<literal>fields</literal>” argument in the request line
154 specifies which fields of the requested objects will be output: 154 specifies which fields of the requested objects will be output:
155 <example> 155 <example>
156 http://127.0.0.1/api/5/nginx?fields=version,build 156 http://127.0.0.1/api/6/nginx?fields=version,build
157 </example> 157 </example>
158 </para> 158 </para>
159 159
160 </directive> 160 </directive>
161 161
197 197
198 <para> 198 <para>
199 <list type="bullet"> 199 <list type="bullet">
200 200
201 <listitem> 201 <listitem>
202 The <link id="stream_limit_conns_">/stream/limit_conns/</link> data
203 were added in <link id="api_version">version</link> 6.
204 </listitem>
205
206 <listitem>
207 The <link id="http_limit_conns_">/http/limit_conns/</link> data
208 were added in <link id="api_version">version</link> 6.
209 </listitem>
210
211 <listitem>
212 The <link id="http_limit_reqs_">/http/limit_reqs/</link> data
213 were added in <link id="api_version">version</link> 6.
214 </listitem>
215
216 <listitem>
202 The “<literal>expire</literal>” parameter of a 217 The “<literal>expire</literal>” parameter of a
203 <link doc="ngx_http_keyval_module.xml">key-value</link> pair can be 218 <link doc="ngx_http_keyval_module.xml">key-value</link> pair can be
204 <link id="postHttpKeyvalZoneData">set</link> or 219 <link id="postHttpKeyvalZoneData">set</link> or
205 <link id="patchHttpKeyvalZoneKeyValue">changed</link> 220 <link id="patchHttpKeyvalZoneKeyValue">changed</link>
206 since <link id="api_version">version</link> 5. 221 since <link id="api_version">version</link> 5.
701 Possible responses: 716 Possible responses:
702 </para> 717 </para>
703 <list type="bullet"> 718 <list type="bullet">
704 <listitem>204 - Success</listitem> 719 <listitem>204 - Success</listitem>
705 <listitem>404 - Cache not found (<literal>CacheNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> 720 <listitem>404 - Cache not found (<literal>CacheNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
721 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
722 </list>
723 </listitem>
724 </list>
725 </tag-desc>
726 <tag-name id="http_limit_conns_" name="/http/limit_conns/">
727 <literal>/http/limit_conns/</literal>
728 </tag-name>
729 <tag-desc>
730 <para>Supported methods:</para>
731 <list type="bullet" compact="yes">
732 <listitem id="getHttpLimitConnZones">
733 <literal>GET</literal> - Return status of all HTTP limit_conn zones
734 <para>Returns status information for each HTTP <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</para>
735 <para>
736 Request parameters:
737 <list type="tag">
738 <tag-name><literal>fields</literal>
739 (<literal>string</literal>, optional)</tag-name>
740 <tag-desc>
741 Limits which fields of limit_conn zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names will be output.</tag-desc>
742 </list>
743 </para>
744 <para>
745 Possible responses:
746 </para>
747 <list type="bullet">
748 <listitem>200 - Success, returns a collection of "<link id="def_nginx_http_limit_conn_zone">HTTP Connections Limiting</link>" objects for all HTTP limit conns</listitem>
749 </list>
750 </listitem>
751 </list>
752 </tag-desc>
753 <tag-name id="http_limit_conns_http_limit_conn_zone_name" name="/http/limit_conns/{httpLimitConnZoneName}">
754 <literal>/http/limit_conns/{httpLimitConnZoneName}</literal>
755 </tag-name>
756 <tag-desc>
757 Parameters common for all methods:
758 <list type="tag">
759 <tag-name><literal>httpLimitConnZoneName</literal>
760 (<literal>string</literal>, required)</tag-name>
761 <tag-desc>
762 The name of a <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</tag-desc>
763 </list>
764 <para>Supported methods:</para>
765 <list type="bullet" compact="yes">
766 <listitem id="getHttpLimitConnZone">
767 <literal>GET</literal> - Return status of an HTTP limit_conn zone
768 <para>Returns status of a particular HTTP <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</para>
769 <para>
770 Request parameters:
771 <list type="tag">
772 <tag-name><literal>fields</literal>
773 (<literal>string</literal>, optional)</tag-name>
774 <tag-desc>
775 Limits which fields of the <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone">limit_conn zone</link> will be output.</tag-desc>
776 </list>
777 </para>
778 <para>
779 Possible responses:
780 </para>
781 <list type="bullet">
782 <listitem>200 - Success, returns <link id="def_nginx_http_limit_conn_zone">HTTP Connections Limiting</link></listitem>
783 <listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
784 </list>
785 </listitem>
786 <listitem id="deleteHttpLimitConnZoneStat">
787 <literal>DELETE</literal> - Reset statistics for an HTTP limit_conn zone
788 <para>Resets the connection limiting statistics.</para>
789 <para>
790 Possible responses:
791 </para>
792 <list type="bullet">
793 <listitem>204 - Success</listitem>
794 <listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
795 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
796 </list>
797 </listitem>
798 </list>
799 </tag-desc>
800 <tag-name id="http_limit_reqs_" name="/http/limit_reqs/">
801 <literal>/http/limit_reqs/</literal>
802 </tag-name>
803 <tag-desc>
804 <para>Supported methods:</para>
805 <list type="bullet" compact="yes">
806 <listitem id="getHttpLimitReqZones">
807 <literal>GET</literal> - Return status of all HTTP limit_req zones
808 <para>Returns status information for each HTTP <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zone</link>.</para>
809 <para>
810 Request parameters:
811 <list type="tag">
812 <tag-name><literal>fields</literal>
813 (<literal>string</literal>, optional)</tag-name>
814 <tag-desc>
815 Limits which fields of limit_req zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names will be output.</tag-desc>
816 </list>
817 </para>
818 <para>
819 Possible responses:
820 </para>
821 <list type="bullet">
822 <listitem>200 - Success, returns a collection of "<link id="def_nginx_http_limit_req_zone">HTTP Requests Rate Limiting</link>" objects for all HTTP limit reqs</listitem>
823 </list>
824 </listitem>
825 </list>
826 </tag-desc>
827 <tag-name id="http_limit_reqs_http_limit_req_zone_name" name="/http/limit_reqs/{httpLimitReqZoneName}">
828 <literal>/http/limit_reqs/{httpLimitReqZoneName}</literal>
829 </tag-name>
830 <tag-desc>
831 Parameters common for all methods:
832 <list type="tag">
833 <tag-name><literal>httpLimitReqZoneName</literal>
834 (<literal>string</literal>, required)</tag-name>
835 <tag-desc>
836 The name of a <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zone</link>.</tag-desc>
837 </list>
838 <para>Supported methods:</para>
839 <list type="bullet" compact="yes">
840 <listitem id="getHttpLimitReqZone">
841 <literal>GET</literal> - Return status of an HTTP limit_req zone
842 <para>Returns status of a particular HTTP <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zone</link>.</para>
843 <para>
844 Request parameters:
845 <list type="tag">
846 <tag-name><literal>fields</literal>
847 (<literal>string</literal>, optional)</tag-name>
848 <tag-desc>
849 Limits which fields of the <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone">limit_req zone</link> will be output.</tag-desc>
850 </list>
851 </para>
852 <para>
853 Possible responses:
854 </para>
855 <list type="bullet">
856 <listitem>200 - Success, returns <link id="def_nginx_http_limit_req_zone">HTTP Requests Rate Limiting</link></listitem>
857 <listitem>404 - limit_req not found (<literal>LimitReqNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
858 </list>
859 </listitem>
860 <listitem id="deleteHttpLimitReqZoneStat">
861 <literal>DELETE</literal> - Reset statistics for an HTTP limit_req zone
862 <para>Resets the requests limiting statistics.</para>
863 <para>
864 Possible responses:
865 </para>
866 <list type="bullet">
867 <listitem>204 - Success</listitem>
868 <listitem>404 - limit_req not found (<literal>LimitReqNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
706 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> 869 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
707 </list> 870 </list>
708 </listitem> 871 </listitem>
709 </list> 872 </list>
710 </tag-desc> 873 </tag-desc>
1155 Possible responses: 1318 Possible responses:
1156 </para> 1319 </para>
1157 <list type="bullet"> 1320 <list type="bullet">
1158 <listitem>204 - Success</listitem> 1321 <listitem>204 - Success</listitem>
1159 <listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> 1322 <listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1323 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1324 </list>
1325 </listitem>
1326 </list>
1327 </tag-desc>
1328 <tag-name id="stream_limit_conns_" name="/stream/limit_conns/">
1329 <literal>/stream/limit_conns/</literal>
1330 </tag-name>
1331 <tag-desc>
1332 <para>Supported methods:</para>
1333 <list type="bullet" compact="yes">
1334 <listitem id="getStreamLimitConnZones">
1335 <literal>GET</literal> - Return status of all stream limit_conn zones
1336 <para>Returns status information for each stream <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</para>
1337 <para>
1338 Request parameters:
1339 <list type="tag">
1340 <tag-name><literal>fields</literal>
1341 (<literal>string</literal>, optional)</tag-name>
1342 <tag-desc>
1343 Limits which fields of limit_conn zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names will be output.</tag-desc>
1344 </list>
1345 </para>
1346 <para>
1347 Possible responses:
1348 </para>
1349 <list type="bullet">
1350 <listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_limit_conn_zone">Stream Connections Limiting</link>" objects for all stream limit conns</listitem>
1351 </list>
1352 </listitem>
1353 </list>
1354 </tag-desc>
1355 <tag-name id="stream_limit_conns_stream_limit_conn_zone_name" name="/stream/limit_conns/{streamLimitConnZoneName}">
1356 <literal>/stream/limit_conns/{streamLimitConnZoneName}</literal>
1357 </tag-name>
1358 <tag-desc>
1359 Parameters common for all methods:
1360 <list type="tag">
1361 <tag-name><literal>streamLimitConnZoneName</literal>
1362 (<literal>string</literal>, required)</tag-name>
1363 <tag-desc>
1364 The name of a <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</tag-desc>
1365 </list>
1366 <para>Supported methods:</para>
1367 <list type="bullet" compact="yes">
1368 <listitem id="getStreamLimitConnZone">
1369 <literal>GET</literal> - Return status of an stream limit_conn zone
1370 <para>Returns status of a particular stream <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zone</link>.</para>
1371 <para>
1372 Request parameters:
1373 <list type="tag">
1374 <tag-name><literal>fields</literal>
1375 (<literal>string</literal>, optional)</tag-name>
1376 <tag-desc>
1377 Limits which fields of the <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_zone">limit_conn zone</link> will be output.</tag-desc>
1378 </list>
1379 </para>
1380 <para>
1381 Possible responses:
1382 </para>
1383 <list type="bullet">
1384 <listitem>200 - Success, returns <link id="def_nginx_stream_limit_conn_zone">Stream Connections Limiting</link></listitem>
1385 <listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1386 </list>
1387 </listitem>
1388 <listitem id="deleteStreamLimitConnZoneStat">
1389 <literal>DELETE</literal> - Reset statistics for a stream limit_conn zone
1390 <para>Resets the connection limiting statistics.</para>
1391 <para>
1392 Possible responses:
1393 </para>
1394 <list type="bullet">
1395 <listitem>204 - Success</listitem>
1396 <listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1160 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> 1397 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1161 </list> 1398 </list>
1162 </listitem> 1399 </listitem>
1163 </list> 1400 </list>
1164 </tag-desc> 1401 </tag-desc>
2336 "responses" : 200187, 2573 "responses" : 200187,
2337 "bytes" : 5510647548, 2574 "bytes" : 5510647548,
2338 "responses_written" : 200173, 2575 "responses_written" : 200173,
2339 "bytes_written" : 44992 2576 "bytes_written" : 44992
2340 } 2577 }
2578 }</example>
2579 </listitem>
2580 <listitem id="def_nginx_http_limit_conn_zone">
2581 <para>HTTP Connections Limiting:</para>
2582 <list type="tag">
2583 <tag-name>
2584 <literal>passed</literal> (<literal>integer</literal>)
2585 </tag-name>
2586 <tag-desc>
2587 The total number of connections that were neither limited nor accounted as limited.
2588 </tag-desc>
2589 <tag-name>
2590 <literal>rejected</literal> (<literal>integer</literal>)
2591 </tag-name>
2592 <tag-desc>
2593 The total number of connections that were rejected.
2594 </tag-desc>
2595 <tag-name>
2596 <literal>rejected_dry_run</literal> (<literal>integer</literal>)
2597 </tag-name>
2598 <tag-desc>
2599 The total number of connections accounted as rejected in the <link url="https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_dry_run">dry run</link> mode.
2600 </tag-desc>
2601 </list>
2602 <para>Example:</para>
2603 <example>
2604 {
2605 "passed" : 15,
2606 "rejected" : 0,
2607 "rejected_dry_run" : 2
2608 }</example>
2609 </listitem>
2610 <listitem id="def_nginx_http_limit_req_zone">
2611 <para>HTTP Requests Rate Limiting:</para>
2612 <list type="tag">
2613 <tag-name>
2614 <literal>passed</literal> (<literal>integer</literal>)
2615 </tag-name>
2616 <tag-desc>
2617 The total number of requests that were neither limited nor accounted as limited.
2618 </tag-desc>
2619 <tag-name>
2620 <literal>delayed</literal> (<literal>integer</literal>)
2621 </tag-name>
2622 <tag-desc>
2623 The total number of requests that were delayed.
2624 </tag-desc>
2625 <tag-name>
2626 <literal>rejected</literal> (<literal>integer</literal>)
2627 </tag-name>
2628 <tag-desc>
2629 The total number of requests that were rejected.
2630 </tag-desc>
2631 <tag-name>
2632 <literal>delayed_dry_run</literal> (<literal>integer</literal>)
2633 </tag-name>
2634 <tag-desc>
2635 The total number of requests accounted as delayed in the <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_dry_run">dry run</link> mode.
2636 </tag-desc>
2637 <tag-name>
2638 <literal>rejected_dry_run</literal> (<literal>integer</literal>)
2639 </tag-name>
2640 <tag-desc>
2641 The total number of requests accounted as rejected in the <link url="https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_dry_run">dry run</link> mode.
2642 </tag-desc>
2643 </list>
2644 <para>Example:</para>
2645 <example>
2646 {
2647 "passed" : 15,
2648 "delayed" : 4,
2649 "rejected" : 0,
2650 "delayed_dry_run" : 1,
2651 "rejected_dry_run" : 2
2341 }</example> 2652 }</example>
2342 </listitem> 2653 </listitem>
2343 <listitem id="def_nginx_http_upstream"> 2654 <listitem id="def_nginx_http_upstream">
2344 <para>HTTP Upstream:</para> 2655 <para>HTTP Upstream:</para>
2345 <list type="tag"> 2656 <list type="tag">
2865 "received" : 4200363, 3176 "received" : 4200363,
2866 "sent" : 20489184 3177 "sent" : 20489184
2867 } 3178 }
2868 }</example> 3179 }</example>
2869 </listitem> 3180 </listitem>
3181 <listitem id="def_nginx_stream_limit_conn_zone">
3182 <para>Stream Connections Limiting:</para>
3183 <list type="tag">
3184 <tag-name>
3185 <literal>passed</literal> (<literal>integer</literal>)
3186 </tag-name>
3187 <tag-desc>
3188 The total number of connections that were neither limited nor accounted as limited.
3189 </tag-desc>
3190 <tag-name>
3191 <literal>rejected</literal> (<literal>integer</literal>)
3192 </tag-name>
3193 <tag-desc>
3194 The total number of connections that were rejected.
3195 </tag-desc>
3196 <tag-name>
3197 <literal>rejected_dry_run</literal> (<literal>integer</literal>)
3198 </tag-name>
3199 <tag-desc>
3200 The total number of connections accounted as rejected in the <link url="https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html#limit_conn_dry_run">dry run</link> mode.
3201 </tag-desc>
3202 </list>
3203 <para>Example:</para>
3204 <example>
3205 {
3206 "passed" : 15,
3207 "rejected" : 0,
3208 "rejected_dry_run" : 2
3209 }</example>
3210 </listitem>
2870 <listitem id="def_nginx_stream_upstream"> 3211 <listitem id="def_nginx_stream_upstream">
2871 <para>Stream Upstream:</para> 3212 <para>Stream Upstream:</para>
2872 <list type="tag"> 3213 <list type="tag">
2873 <tag-name> 3214 <tag-name>
2874 <literal>peers</literal></tag-name> 3215 <literal>peers</literal></tag-name>