Mercurial > hg > nginx-site

diff 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
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_api_module.xml	Wed Nov 27 17:09:36 2019 +0300
+++ b/xml/en/docs/http/ngx_http_api_module.xml	Mon Dec 02 13:23:05 2019 +0300
@@ -101,21 +101,21 @@
 a supported API <link id="api_version">version</link> in the URI.
 Examples of API requests with this configuration:
 <example>
-http://127.0.0.1/api/5/
-http://127.0.0.1/api/5/nginx
-http://127.0.0.1/api/5/connections
-http://127.0.0.1/api/5/http/requests
-http://127.0.0.1/api/5/http/server_zones/server_backend
-http://127.0.0.1/api/5/http/caches/cache_backend
-http://127.0.0.1/api/5/http/upstreams/backend
-http://127.0.0.1/api/5/http/upstreams/backend/servers/
-http://127.0.0.1/api/5/http/upstreams/backend/servers/1
-http://127.0.0.1/api/5/http/keyvals/one?key=arg1
-http://127.0.0.1/api/5/stream/
-http://127.0.0.1/api/5/stream/server_zones/server_backend
-http://127.0.0.1/api/5/stream/upstreams/
-http://127.0.0.1/api/5/stream/upstreams/backend
-http://127.0.0.1/api/5/stream/upstreams/backend/servers/1
+http://127.0.0.1/api/6/
+http://127.0.0.1/api/6/nginx
+http://127.0.0.1/api/6/connections
+http://127.0.0.1/api/6/http/requests
+http://127.0.0.1/api/6/http/server_zones/server_backend
+http://127.0.0.1/api/6/http/caches/cache_backend
+http://127.0.0.1/api/6/http/upstreams/backend
+http://127.0.0.1/api/6/http/upstreams/backend/servers/
+http://127.0.0.1/api/6/http/upstreams/backend/servers/1
+http://127.0.0.1/api/6/http/keyvals/one?key=arg1
+http://127.0.0.1/api/6/stream/
+http://127.0.0.1/api/6/stream/server_zones/server_backend
+http://127.0.0.1/api/6/stream/upstreams/
+http://127.0.0.1/api/6/stream/upstreams/backend
+http://127.0.0.1/api/6/stream/upstreams/backend/servers/1
 </example>
 </para>
 
@@ -146,14 +146,14 @@
 All API requests should contain a supported API version in the URI.
 If the request URI equals the location prefix,
 the list of supported API versions is returned.
-The current API version is “<literal>5</literal>”.
+The current API version is “<literal>6</literal>”.
 </para>
 
 <para>
 The optional “<literal>fields</literal>” argument in the request line
 specifies which fields of the requested objects will be output:
 <example>
-http://127.0.0.1/api/5/nginx?fields=version,build
+http://127.0.0.1/api/6/nginx?fields=version,build
 </example>
 </para>
 
@@ -199,6 +199,21 @@
 <list type="bullet">
 
 <listitem>
+The <link id="stream_limit_conns_">/stream/limit_conns/</link> data
+were added in <link id="api_version">version</link> 6.
+</listitem>
+
+<listitem>
+The <link id="http_limit_conns_">/http/limit_conns/</link> data
+were added in <link id="api_version">version</link> 6.
+</listitem>
+
+<listitem>
+The <link id="http_limit_reqs_">/http/limit_reqs/</link> data
+were added in <link id="api_version">version</link> 6.
+</listitem>
+
+<listitem>
 The “<literal>expire</literal>” parameter of a
 <link doc="ngx_http_keyval_module.xml">key-value</link> pair can be
 <link id="postHttpKeyvalZoneData">set</link> or
@@ -708,6 +723,154 @@
 </listitem>
 </list>
 </tag-desc>
+<tag-name id="http_limit_conns_" name="/http/limit_conns/">
+<literal>/http/limit_conns/</literal>
+</tag-name>
+<tag-desc>
+<para>Supported methods:</para>
+<list type="bullet" compact="yes">
+<listitem id="getHttpLimitConnZones">
+<literal>GET</literal> - Return status of all HTTP limit_conn zones
+<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>
+<para>
+Request parameters:
+<list type="tag">
+<tag-name><literal>fields</literal>
+(<literal>string</literal>, optional)</tag-name>
+<tag-desc>
+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>
+</list>
+</para>
+<para>
+Possible responses:
+</para>
+<list type="bullet">
+<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>
+</list>
+</listitem>
+</list>
+</tag-desc>
+<tag-name id="http_limit_conns_http_limit_conn_zone_name" name="/http/limit_conns/{httpLimitConnZoneName}">
+<literal>/http/limit_conns/{httpLimitConnZoneName}</literal>
+</tag-name>
+<tag-desc>
+Parameters common for all methods:
+<list type="tag">
+<tag-name><literal>httpLimitConnZoneName</literal>
+(<literal>string</literal>, required)</tag-name>
+<tag-desc>
+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>
+</list>
+<para>Supported methods:</para>
+<list type="bullet" compact="yes">
+<listitem id="getHttpLimitConnZone">
+<literal>GET</literal> - Return status of an HTTP limit_conn zone
+<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>
+<para>
+Request parameters:
+<list type="tag">
+<tag-name><literal>fields</literal>
+(<literal>string</literal>, optional)</tag-name>
+<tag-desc>
+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>
+</list>
+</para>
+<para>
+Possible responses:
+</para>
+<list type="bullet">
+<listitem>200 - Success, returns <link id="def_nginx_http_limit_conn_zone">HTTP Connections Limiting</link></listitem>
+<listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
+</list>
+</listitem>
+<listitem id="deleteHttpLimitConnZoneStat">
+<literal>DELETE</literal> - Reset statistics for an HTTP limit_conn zone
+<para>Resets the connection limiting statistics.</para>
+<para>
+Possible responses:
+</para>
+<list type="bullet">
+<listitem>204 - Success</listitem>
+<listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
+<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
+</list>
+</listitem>
+</list>
+</tag-desc>
+<tag-name id="http_limit_reqs_" name="/http/limit_reqs/">
+<literal>/http/limit_reqs/</literal>
+</tag-name>
+<tag-desc>
+<para>Supported methods:</para>
+<list type="bullet" compact="yes">
+<listitem id="getHttpLimitReqZones">
+<literal>GET</literal> - Return status of all HTTP limit_req zones
+<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>
+<para>
+Request parameters:
+<list type="tag">
+<tag-name><literal>fields</literal>
+(<literal>string</literal>, optional)</tag-name>
+<tag-desc>
+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>
+</list>
+</para>
+<para>
+Possible responses:
+</para>
+<list type="bullet">
+<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>
+</list>
+</listitem>
+</list>
+</tag-desc>
+<tag-name id="http_limit_reqs_http_limit_req_zone_name" name="/http/limit_reqs/{httpLimitReqZoneName}">
+<literal>/http/limit_reqs/{httpLimitReqZoneName}</literal>
+</tag-name>
+<tag-desc>
+Parameters common for all methods:
+<list type="tag">
+<tag-name><literal>httpLimitReqZoneName</literal>
+(<literal>string</literal>, required)</tag-name>
+<tag-desc>
+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>
+</list>
+<para>Supported methods:</para>
+<list type="bullet" compact="yes">
+<listitem id="getHttpLimitReqZone">
+<literal>GET</literal> - Return status of an HTTP limit_req zone
+<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>
+<para>
+Request parameters:
+<list type="tag">
+<tag-name><literal>fields</literal>
+(<literal>string</literal>, optional)</tag-name>
+<tag-desc>
+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>
+</list>
+</para>
+<para>
+Possible responses:
+</para>
+<list type="bullet">
+<listitem>200 - Success, returns <link id="def_nginx_http_limit_req_zone">HTTP Requests Rate Limiting</link></listitem>
+<listitem>404 - limit_req not found (<literal>LimitReqNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
+</list>
+</listitem>
+<listitem id="deleteHttpLimitReqZoneStat">
+<literal>DELETE</literal> - Reset statistics for an HTTP limit_req zone
+<para>Resets the requests limiting statistics.</para>
+<para>
+Possible responses:
+</para>
+<list type="bullet">
+<listitem>204 - Success</listitem>
+<listitem>404 - limit_req not found (<literal>LimitReqNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
+<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
+</list>
+</listitem>
+</list>
+</tag-desc>
 <tag-name id="http_upstreams_" name="/http/upstreams/">
 <literal>/http/upstreams/</literal>
 </tag-name>
@@ -1162,6 +1325,80 @@
 </listitem>
 </list>
 </tag-desc>
+<tag-name id="stream_limit_conns_" name="/stream/limit_conns/">
+<literal>/stream/limit_conns/</literal>
+</tag-name>
+<tag-desc>
+<para>Supported methods:</para>
+<list type="bullet" compact="yes">
+<listitem id="getStreamLimitConnZones">
+<literal>GET</literal> - Return status of all stream limit_conn zones
+<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>
+<para>
+Request parameters:
+<list type="tag">
+<tag-name><literal>fields</literal>
+(<literal>string</literal>, optional)</tag-name>
+<tag-desc>
+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>
+</list>
+</para>
+<para>
+Possible responses:
+</para>
+<list type="bullet">
+<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>
+</list>
+</listitem>
+</list>
+</tag-desc>
+<tag-name id="stream_limit_conns_stream_limit_conn_zone_name" name="/stream/limit_conns/{streamLimitConnZoneName}">
+<literal>/stream/limit_conns/{streamLimitConnZoneName}</literal>
+</tag-name>
+<tag-desc>
+Parameters common for all methods:
+<list type="tag">
+<tag-name><literal>streamLimitConnZoneName</literal>
+(<literal>string</literal>, required)</tag-name>
+<tag-desc>
+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>
+</list>
+<para>Supported methods:</para>
+<list type="bullet" compact="yes">
+<listitem id="getStreamLimitConnZone">
+<literal>GET</literal> - Return status of an stream limit_conn zone
+<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>
+<para>
+Request parameters:
+<list type="tag">
+<tag-name><literal>fields</literal>
+(<literal>string</literal>, optional)</tag-name>
+<tag-desc>
+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>
+</list>
+</para>
+<para>
+Possible responses:
+</para>
+<list type="bullet">
+<listitem>200 - Success, returns <link id="def_nginx_stream_limit_conn_zone">Stream Connections Limiting</link></listitem>
+<listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
+</list>
+</listitem>
+<listitem id="deleteStreamLimitConnZoneStat">
+<literal>DELETE</literal> - Reset statistics for a stream limit_conn zone
+<para>Resets the connection limiting statistics.</para>
+<para>
+Possible responses:
+</para>
+<list type="bullet">
+<listitem>204 - Success</listitem>
+<listitem>404 - limit_conn not found (<literal>LimitConnNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
+<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
+</list>
+</listitem>
+</list>
+</tag-desc>
 <tag-name id="stream_upstreams_" name="/stream/upstreams/">
 <literal>/stream/upstreams/</literal>
 </tag-name>
@@ -2340,6 +2577,80 @@
   }
 }</example>
 </listitem>
+<listitem id="def_nginx_http_limit_conn_zone">
+<para>HTTP Connections Limiting:</para>
+<list type="tag">
+<tag-name>
+<literal>passed</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+The total number of connections that were neither limited nor accounted as limited.
+</tag-desc>
+<tag-name>
+<literal>rejected</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+The total number of connections that were rejected.
+</tag-desc>
+<tag-name>
+<literal>rejected_dry_run</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+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.
+</tag-desc>
+</list>
+<para>Example:</para>
+<example>
+{
+  "passed" : 15,
+  "rejected" : 0,
+  "rejected_dry_run" : 2
+}</example>
+</listitem>
+<listitem id="def_nginx_http_limit_req_zone">
+<para>HTTP Requests Rate Limiting:</para>
+<list type="tag">
+<tag-name>
+<literal>passed</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+The total number of requests that were neither limited nor accounted as limited.
+</tag-desc>
+<tag-name>
+<literal>delayed</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+The total number of requests that were delayed.
+</tag-desc>
+<tag-name>
+<literal>rejected</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+The total number of requests that were rejected.
+</tag-desc>
+<tag-name>
+<literal>delayed_dry_run</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+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.
+</tag-desc>
+<tag-name>
+<literal>rejected_dry_run</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+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.
+</tag-desc>
+</list>
+<para>Example:</para>
+<example>
+{
+  "passed" : 15,
+  "delayed" : 4,
+  "rejected" : 0,
+  "delayed_dry_run" : 1,
+  "rejected_dry_run" : 2
+}</example>
+</listitem>
 <listitem id="def_nginx_http_upstream">
 <para>HTTP Upstream:</para>
 <list type="tag">
@@ -2867,6 +3178,36 @@
   }
 }</example>
 </listitem>
+<listitem id="def_nginx_stream_limit_conn_zone">
+<para>Stream Connections Limiting:</para>
+<list type="tag">
+<tag-name>
+<literal>passed</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+The total number of connections that were neither limited nor accounted as limited.
+</tag-desc>
+<tag-name>
+<literal>rejected</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+The total number of connections that were rejected.
+</tag-desc>
+<tag-name>
+<literal>rejected_dry_run</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+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.
+</tag-desc>
+</list>
+<para>Example:</para>
+<example>
+{
+  "passed" : 15,
+  "rejected" : 0,
+  "rejected_dry_run" : 2
+}</example>
+</listitem>
 <listitem id="def_nginx_stream_upstream">
 <para>Stream Upstream:</para>
 <list type="tag">