Mercurial > hg > nginx-site
changeset 2424:dd3ac7eefeed
Updated docs for the upcoming NGINX Plus release.
| author | Ruslan Ermilov <ru@nginx.com> |
|---|---|
| date | Mon, 02 Sep 2019 14:12:20 +0300 |
| parents | 21f1376238b0 |
| children | b64dd047de68 |
| files | xml/en/docs/http/ngx_http_api_module.xml xml/en/docs/http/ngx_http_api_module_head.xml xml/en/docs/http/ngx_http_auth_jwt_module.xml xml/en/docs/http/ngx_http_core_module.xml xml/en/docs/http/ngx_http_keyval_module.xml xml/en/docs/stream/ngx_stream_keyval_module.xml xml/ru/docs/http/ngx_http_auth_jwt_module.xml xml/ru/docs/http/ngx_http_core_module.xml yaml/nginx_api.yaml yaml/yaml2xml.py |
| diffstat | 10 files changed, 1095 insertions(+), 198 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_api_module.xml Thu Aug 22 23:00:31 2019 +0300 +++ b/xml/en/docs/http/ngx_http_api_module.xml Mon Sep 02 14:12:20 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/4/ -http://127.0.0.1/api/4/nginx -http://127.0.0.1/api/4/connections -http://127.0.0.1/api/4/http/requests -http://127.0.0.1/api/4/http/server_zones/server_backend -http://127.0.0.1/api/4/http/caches/cache_backend -http://127.0.0.1/api/4/http/upstreams/backend -http://127.0.0.1/api/4/http/upstreams/backend/servers/ -http://127.0.0.1/api/4/http/upstreams/backend/servers/1 -http://127.0.0.1/api/4/http/keyvals/one?key=arg1 -http://127.0.0.1/api/4/stream/ -http://127.0.0.1/api/4/stream/server_zones/server_backend -http://127.0.0.1/api/4/stream/upstreams/ -http://127.0.0.1/api/4/stream/upstreams/backend -http://127.0.0.1/api/4/stream/upstreams/backend/servers/1 +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 </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>4</literal>”. +The current API version is “<literal>5</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/4/nginx?fields=version,build +http://127.0.0.1/api/5/nginx?fields=version,build </example> </para> @@ -164,6 +164,8 @@ <syntax><value>zone</value></syntax> <default/> <context>server</context> +<context>location</context> +<context>if in location</context> <appeared-in>1.13.12</appeared-in> <para> @@ -175,6 +177,18 @@ Several servers may share the same zone. </para> +<para id="status_zone_location"> +Starting from 1.17.0, status information can be collected +per <link doc="ngx_http_core_module.xml" id="location"/>. +The special value <literal>off</literal> disables statistics collection +in nested location blocks. +Note that the statistics is collected +in the context of a location where processing ends. +It may be different from the original location, if an +<link doc="ngx_http_core_module.xml" id="internal">internal +redirect</link> happens during request processing. +</para> + </directive> </section> @@ -185,6 +199,24 @@ <list type="bullet"> <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 +<link id="patchHttpKeyvalZoneKeyValue">changed</link> +since <link id="api_version">version</link> 5. +</listitem> + +<listitem> +The <link id="resolvers_">/resolvers/</link> data +were added in <link id="api_version">version</link> 5. +</listitem> + +<listitem> +The <link id="http_location_zones_">/http/location_zones/</link> data +were added in <link id="api_version">version</link> 5. +</listitem> + +<listitem> The <literal>path</literal> and <literal>method</literal> fields of <link id="def_nginx_error">nginx error object</link> were removed in <link id="api_version">version</link> 4. @@ -324,43 +356,6 @@ </listitem> </list> </tag-desc> -<tag-name id="ssl" name="/ssl"> -<literal>/ssl</literal> -</tag-name> -<tag-desc> -<para>Supported methods:</para> -<list type="bullet" compact="yes"> -<listitem id="getSsl"> -<literal>GET</literal> - Return SSL statistics -<para>Returns SSL statistics.</para> -<para> -Request parameters: -<list type="tag"> -<tag-name><literal>fields</literal> -(<literal>string</literal>, optional)</tag-name> -<tag-desc> -Limits which fields of SSL statistics will be output.</tag-desc> -</list> -</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>200 - Success, returns <link id="def_nginx_ssl_object">SSL</link></listitem> -</list> -</listitem> -<listitem id="deleteSslStat"> -<literal>DELETE</literal> - Reset SSL statistics -<para>Resets counters of SSL handshakes and session reuses.</para> -<para> -Possible responses: -</para> -<list type="bullet"> -<listitem>204 - Success</listitem> -</list> -</listitem> -</list> -</tag-desc> <tag-name id="slabs_" name="/slabs/"> <literal>/slabs/</literal> </tag-name> @@ -376,14 +371,14 @@ <tag-name><literal>fields</literal> (<literal>string</literal>, optional)</tag-name> <tag-desc> -Limits which fields of slab zones will be output. If the “<literal>fields</literal>” value is empty, then only zone names are output.</tag-desc> +Limits which fields of slab 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_slab_zone">Shared memory zone with slab allocator</link>" objects for all slabs </listitem> +<listitem>200 - Success, returns a collection of "<link id="def_nginx_slab_zone">Shared memory zone with slab allocator</link>" objects for all slabs</listitem> </list> </listitem> </list> @@ -506,14 +501,14 @@ <tag-name><literal>fields</literal> (<literal>string</literal>, optional)</tag-name> <tag-desc> -Limits which fields of server zones will be output. If the “<literal>fields</literal>” value is empty, then only server zone names are output.</tag-desc> +Limits which fields of server zones will be output. If the “<literal>fields</literal>” value is empty, then only server 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_server_zone">HTTP Server Zone</link>" objects for all http server zones </listitem> +<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_server_zone">HTTP Server Zone</link>" objects for all HTTP server zones</listitem> </list> </listitem> </list> @@ -565,6 +560,80 @@ </listitem> </list> </tag-desc> +<tag-name id="http_location_zones_" name="/http/location_zones/"> +<literal>/http/location_zones/</literal> +</tag-name> +<tag-desc> +<para>Supported methods:</para> +<list type="bullet" compact="yes"> +<listitem id="getHttpLocationZones"> +<literal>GET</literal> - Return status of all HTTP location zones +<para>Returns status information for each HTTP <link url="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone_location">location 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 location 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_location_zone">HTTP Location Zone</link>" objects for all HTTP location zones</listitem> +</list> +</listitem> +</list> +</tag-desc> +<tag-name id="http_location_zones_http_location_zone_name" name="/http/location_zones/{httpLocationZoneName}"> +<literal>/http/location_zones/{httpLocationZoneName}</literal> +</tag-name> +<tag-desc> +Parameters common for all methods: +<list type="tag"> +<tag-name><literal>httpLocationZoneName</literal> +(<literal>string</literal>, required)</tag-name> +<tag-desc> +The name of an HTTP <link url="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone_location">location zone</link>.</tag-desc> +</list> +<para>Supported methods:</para> +<list type="bullet" compact="yes"> +<listitem id="getHttpLocationZone"> +<literal>GET</literal> - Return status of an HTTP location zone +<para>Returns status of a particular HTTP <link url="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone_location">location 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 location zone will be output.</tag-desc> +</list> +</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>200 - Success, returns <link id="def_nginx_http_location_zone">HTTP Location Zone</link></listitem> +<listitem>404 - Location zone not found (<literal>LocationZoneNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> +</list> +</listitem> +<listitem id="deleteHttpLocationZoneStat"> +<literal>DELETE</literal> - Reset statistics for a location zone. +<para>Resets statistics of accepted and discarded requests, responses, received and sent bytes in a particular location zone.</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>204 - Success</listitem> +<listitem>404 - Location zone not found (<literal>LocationZoneNotFound</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_caches_" name="/http/caches/"> <literal>/http/caches/</literal> </tag-name> @@ -580,14 +649,14 @@ <tag-name><literal>fields</literal> (<literal>string</literal>, optional)</tag-name> <tag-desc> -Limits which fields of cache zones will be output. If the “<literal>fields</literal>” value is empty, then only names of cache zones are output.</tag-desc> +Limits which fields of cache zones will be output. If the “<literal>fields</literal>” value is empty, then only names of cache zones 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_cache">HTTP Cache</link>" objects for all http caches </listitem> +<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_cache">HTTP Cache</link>" objects for all HTTP caches</listitem> </list> </listitem> </list> @@ -654,14 +723,14 @@ <tag-name><literal>fields</literal> (<literal>string</literal>, optional)</tag-name> <tag-desc> -Limits which fields of upstream server groups will be output. If the “<literal>fields</literal>” value is empty, only names of upstreams are output.</tag-desc> +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.</tag-desc> </list> </para> <para> Possible responses: </para> <list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_upstream">HTTP Upstream</link>" objects for all http upstreams </listitem> +<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_upstream">HTTP Upstream</link>" objects for all HTTP upstreams</listitem> </list> </listitem> </list> @@ -886,14 +955,14 @@ <tag-name><literal>fields</literal> (<literal>string</literal>, optional)</tag-name> <tag-desc> -If the “<literal>fields</literal>” value is empty, then only HTTP keyval zone names are output.</tag-desc> +If the “<literal>fields</literal>” value is empty, then only HTTP keyval 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_keyval_zone">HTTP Keyval Shared Memory Zone</link>" objects for all http keyvals </listitem> +<listitem>200 - Success, returns a collection of "<link id="def_nginx_http_keyval_zone">HTTP Keyval Shared Memory Zone</link>" objects for all HTTP keyvals</listitem> </list> </listitem> </list> @@ -939,9 +1008,9 @@ Request parameters: <list type="tag"> <tag-name><literal>Key-value</literal> -(<link id="def_nginx_http_keyval_zone">HTTP Keyval Shared Memory Zone</link>, required)</tag-name> -<tag-desc> -A key-value pair is specified in the JSON format. Several key-value pairs can be entered if the HTTP keyval shared memory zone is empty.</tag-desc> +(<link id="def_nginx_http_keyval_zone_post_patch">HTTP Keyval Shared Memory Zone</link>, required)</tag-name> +<tag-desc> +A key-value pair is specified in the JSON format. Several key-value pairs can be entered if the HTTP keyval shared memory zone is empty. Expiration time in milliseconds can be specified for a key-value pair with the <literal>expire</literal> parameter which overrides the <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_timeout"><literal>timeout</literal></link> parameter of the <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">keyval_zone</link> directive.</tag-desc> </list> </para> <para> @@ -949,9 +1018,11 @@ </para> <list type="bullet"> <listitem>201 - Created</listitem> -<listitem>400 - Key required (<literal>KeyvalFormatError</literal>), -only one key can be added (<literal>KeyvalFormatError</literal>), -nested object or list (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> +<listitem>400 - Invalid JSON (<literal>KeyvalFormatError</literal>), +invalid key format (<literal>KeyvalFormatError</literal>), +key required (<literal>KeyvalFormatError</literal>), +keyval timeout is not enabled (<literal>KeyvalFormatError</literal>), +only one key can be added (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> <listitem>404 - Keyval not found (<literal>KeyvalNotFound</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> <listitem>409 - Key already exists (<literal>KeyvalKeyExists</literal>), returns <link id="def_nginx_error">Error</link></listitem> @@ -960,12 +1031,12 @@ </listitem> <listitem id="patchHttpKeyvalZoneKeyValue"> <literal>PATCH</literal> - Modify a key-value or delete a key -<para>Changes the value of the selected key in the key-value pair or deletes a key by setting the key value to <literal>null</literal>. If <link url="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</link> of keyval zones in a cluster is enabled, deletes a key only on a target cluster node.</para> +<para>Changes the value of the selected key in the key-value pair, deletes a key by setting the key value to <literal>null</literal>, changes expiration time of a key-value pair. If <link url="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</link> of keyval zones in a cluster is enabled, deletes a key only on a target cluster node. Expiration time in milliseconds can be specified for a key-value pair with the <literal>expire</literal> parameter which overrides the <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_timeout"><literal>timeout</literal></link> parameter of the <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">keyval_zone</link> directive.</para> <para> Request parameters: <list type="tag"> <tag-name><literal>httpKeyvalZoneKeyValue</literal> -(<link id="def_nginx_http_keyval_zone">HTTP Keyval Shared Memory Zone</link>, required)</tag-name> +(<link id="def_nginx_http_keyval_zone_post_patch">HTTP Keyval Shared Memory Zone</link>, required)</tag-name> <tag-desc> A new value for the key is specified in the JSON format.</tag-desc> </list> @@ -975,9 +1046,10 @@ </para> <list type="bullet"> <listitem>204 - Success</listitem> -<listitem>400 - Key required (<literal>KeyvalFormatError</literal>), -only one key can be updated (<literal>KeyvalFormatError</literal>), -nested object or list (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> +<listitem>400 - Invalid JSON (<literal>KeyvalFormatError</literal>), +key required (<literal>KeyvalFormatError</literal>), +keyval timeout is not enabled (<literal>KeyvalFormatError</literal>), +only one key can be updated (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), keyval key not found (<literal>KeyvalKeyNotFound</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> @@ -1031,14 +1103,14 @@ <tag-name><literal>fields</literal> (<literal>string</literal>, optional)</tag-name> <tag-desc> -Limits which fields of server zones will be output. If the “<literal>fields</literal>” value is empty, then only server zone names are output.</tag-desc> +Limits which fields of server zones will be output. If the “<literal>fields</literal>” value is empty, then only server 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_server_zone">Stream Server Zone</link>" objects for all stream server zones </listitem> +<listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_server_zone">Stream Server Zone</link>" objects for all stream server zones</listitem> </list> </listitem> </list> @@ -1105,14 +1177,14 @@ <tag-name><literal>fields</literal> (<literal>string</literal>, optional)</tag-name> <tag-desc> -Limits which fields of upstream server groups will be output. If the “<literal>fields</literal>” value is empty, only names of upstreams are output.</tag-desc> +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.</tag-desc> </list> </para> <para> Possible responses: </para> <list type="bullet"> -<listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_upstream">Stream Upstream</link>" objects for all stream upstreams </listitem> +<listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_upstream">Stream Upstream</link>" objects for all stream upstreams</listitem> </list> </listitem> </list> @@ -1337,14 +1409,14 @@ <tag-name><literal>fields</literal> (<literal>string</literal>, optional)</tag-name> <tag-desc> -If the “<literal>fields</literal>” value is empty, then only stream keyval zone names are output.</tag-desc> +If the “<literal>fields</literal>” value is empty, then only stream keyval 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_keyval_zone">Stream Keyval Shared Memory Zone</link>" objects for all stream keyvals </listitem> +<listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_keyval_zone">Stream Keyval Shared Memory Zone</link>" objects for all stream keyvals</listitem> </list> </listitem> </list> @@ -1390,9 +1462,9 @@ Request parameters: <list type="tag"> <tag-name><literal>Key-value</literal> -(<link id="def_nginx_stream_keyval_zone">Stream Keyval Shared Memory Zone</link>, required)</tag-name> -<tag-desc> -A key-value pair is specified in the JSON format. Several key-value pairs can be entered if the stream keyval shared memory zone is empty.</tag-desc> +(<link id="def_nginx_stream_keyval_zone_post_patch">Stream Keyval Shared Memory Zone</link>, required)</tag-name> +<tag-desc> +A key-value pair is specified in the JSON format. Several key-value pairs can be entered if the stream keyval shared memory zone is empty. Expiration time in milliseconds can be specified for a key-value pair with the <literal>expire</literal> parameter which overrides the <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_timeout"><literal>timeout</literal></link> parameter of the <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">keyval_zone</link> directive.</tag-desc> </list> </para> <para> @@ -1400,9 +1472,11 @@ </para> <list type="bullet"> <listitem>201 - Created</listitem> -<listitem>400 - Key required (<literal>KeyvalFormatError</literal>), -only one key can be added (<literal>KeyvalFormatError</literal>), -nested object or list (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> +<listitem>400 - Invalid JSON (<literal>KeyvalFormatError</literal>), +invalid key format (<literal>KeyvalFormatError</literal>), +key required (<literal>KeyvalFormatError</literal>), +keyval timeout is not enabled (<literal>KeyvalFormatError</literal>), +only one key can be added (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> <listitem>404 - Keyval not found (<literal>KeyvalNotFound</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> <listitem>409 - Key already exists (<literal>KeyvalKeyExists</literal>), returns <link id="def_nginx_error">Error</link></listitem> @@ -1411,12 +1485,12 @@ </listitem> <listitem id="patchStreamKeyvalZoneKeyValue"> <literal>PATCH</literal> - Modify a key-value or delete a key -<para>Changes the value of the selected key in the key-value pair or deletes a key by setting the key value to <literal>null</literal>. If <link url="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</link> of keyval zones in a cluster is enabled, deletes a key only on a target cluster node.</para> +<para>Changes the value of the selected key in the key-value pair, deletes a key by setting the key value to <literal>null</literal>, changes expiration time of a key-value pair. If <link url="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</link> of keyval zones in a cluster is enabled, deletes a key only on a target cluster node. Expiration time is specified in milliseconds with the <literal>expire</literal> parameter which overrides the <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_timeout"><literal>timeout</literal></link> parameter of the <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">keyval_zone</link> directive.</para> <para> Request parameters: <list type="tag"> <tag-name><literal>streamKeyvalZoneKeyValue</literal> -(<link id="def_nginx_stream_keyval_zone">Stream Keyval Shared Memory Zone</link>, required)</tag-name> +(<link id="def_nginx_stream_keyval_zone_post_patch">Stream Keyval Shared Memory Zone</link>, required)</tag-name> <tag-desc> A new value for the key is specified in the JSON format.</tag-desc> </list> @@ -1426,9 +1500,10 @@ </para> <list type="bullet"> <listitem>204 - Success</listitem> -<listitem>400 - Key required (<literal>KeyvalFormatError</literal>), -only one key can be updated (<literal>KeyvalFormatError</literal>), -nested object or list (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> +<listitem>400 - Invalid JSON (<literal>KeyvalFormatError</literal>), +key required (<literal>KeyvalFormatError</literal>), +keyval timeout is not enabled (<literal>KeyvalFormatError</literal>), +only one key can be updated (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), keyval key not found (<literal>KeyvalKeyNotFound</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> @@ -1467,6 +1542,117 @@ </listitem> </list> </tag-desc> +<tag-name id="resolvers_" name="/resolvers/"> +<literal>/resolvers/</literal> +</tag-name> +<tag-desc> +<para>Supported methods:</para> +<list type="bullet" compact="yes"> +<listitem id="getResolverZones"> +<literal>GET</literal> - Return status for all resolver zones +<para>Returns status information for each <link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone">resolver 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 resolvers statistics 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_resolver_zone">Resolver Zone</link>" objects for all resolvers</listitem> +</list> +</listitem> +</list> +</tag-desc> +<tag-name id="resolvers_resolver_zone_name" name="/resolvers/{resolverZoneName}"> +<literal>/resolvers/{resolverZoneName}</literal> +</tag-name> +<tag-desc> +Parameters common for all methods: +<list type="tag"> +<tag-name><literal>resolverZoneName</literal> +(<literal>string</literal>, required)</tag-name> +<tag-desc> +The name of a resolver zone.</tag-desc> +</list> +<para>Supported methods:</para> +<list type="bullet" compact="yes"> +<listitem id="getResolverZone"> +<literal>GET</literal> - Return statistics of a resolver zone +<para>Returns statistics stored in a particular resolver <link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone">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 resolver zone will be output (requests, responses, or both).</tag-desc> +</list> +</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>200 - Success, returns <link id="def_nginx_resolver_zone">Resolver Zone</link></listitem> +<listitem>404 - Resolver zone not found (<literal>ResolverZoneNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> +</list> +</listitem> +<listitem id="deleteResolverZoneStat"> +<literal>DELETE</literal> - Reset statistics for a resolver zone. +<para>Resets statistics in a particular resolver zone.</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>204 - Success</listitem> +<listitem>404 - Resolver zone not found (<literal>ResolverZoneNotFound</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="ssl" name="/ssl"> +<literal>/ssl</literal> +</tag-name> +<tag-desc> +<para>Supported methods:</para> +<list type="bullet" compact="yes"> +<listitem id="getSsl"> +<literal>GET</literal> - Return SSL statistics +<para>Returns SSL statistics.</para> +<para> +Request parameters: +<list type="tag"> +<tag-name><literal>fields</literal> +(<literal>string</literal>, optional)</tag-name> +<tag-desc> +Limits which fields of SSL statistics will be output.</tag-desc> +</list> +</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>200 - Success, returns <link id="def_nginx_ssl_object">SSL</link></listitem> +</list> +</listitem> +<listitem id="deleteSslStat"> +<literal>DELETE</literal> - Reset SSL statistics +<para>Resets counters of SSL handshakes and session reuses.</para> +<para> +Possible responses: +</para> +<list type="bullet"> +<listitem>204 - Success</listitem> +</list> +</listitem> +</list> +</tag-desc> </list> </para> </section> @@ -1843,6 +2029,93 @@ "sent" : 19415530115 }</example> </listitem> +<listitem id="def_nginx_http_location_zone"> +<para>HTTP Location Zone:</para> +<list type="tag"> +<tag-name> +<literal>requests</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of client requests received from clients. +</tag-desc> +<tag-name> +<literal>responses</literal></tag-name> +<tag-desc> +The total number of responses sent to clients and the number of responses with status codes “<literal>1xx</literal>”, “<literal>2xx</literal>”, “<literal>3xx</literal>”, “<literal>4xx</literal>”, and “<literal>5xx</literal>”.<list type="tag"> +<tag-name> +<literal>1xx</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The number of responses with “<literal>1xx</literal>” status codes. +</tag-desc> +<tag-name> +<literal>2xx</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The number of responses with “<literal>2xx</literal>” status codes. +</tag-desc> +<tag-name> +<literal>3xx</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The number of responses with “<literal>3xx</literal>” status codes. +</tag-desc> +<tag-name> +<literal>4xx</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The number of responses with “<literal>4xx</literal>” status codes. +</tag-desc> +<tag-name> +<literal>5xx</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The number of responses with “<literal>5xx</literal>” status codes. +</tag-desc> +<tag-name> +<literal>total</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of responses sent to clients. +</tag-desc> +</list> +</tag-desc> +<tag-name> +<literal>discarded</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of requests completed without sending a response. +</tag-desc> +<tag-name> +<literal>received</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of bytes received from clients. +</tag-desc> +<tag-name> +<literal>sent</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of bytes sent to clients. +</tag-desc> +</list> +<para>Example:</para> +<example> +{ + "requests" : 706690, + "responses" : { + "1xx" : 0, + "2xx" : 699482, + "3xx" : 4522, + "4xx" : 907, + "5xx" : 266, + "total" : 705177 + }, + "discarded" : 1513, + "received" : 172711587, + "sent" : 19415530115 +}</example> +</listitem> <listitem id="def_nginx_http_cache"> <para>HTTP Cache:</para> <list type="tag"> @@ -2489,7 +2762,8 @@ </listitem> <listitem id="def_nginx_http_keyval_zone"> <para>HTTP Keyval Shared Memory Zone:</para> -Contents of an HTTP keyval shared memory zone.<para>Example:</para> +Contents of an HTTP keyval shared memory zone +when using the GET method.<para>Example:</para> <example> { "key1" : "value1", @@ -2497,6 +2771,20 @@ "key3" : "value3" }</example> </listitem> +<listitem id="def_nginx_http_keyval_zone_post_patch"> +<para>HTTP Keyval Shared Memory Zone:</para> +Contents of an HTTP keyval shared memory zone +when using the POST or PATCH methods.<para>Example:</para> +<example> +{ + "key1" : "value1", + "key2" : "value2", + "key3" : { + "value" : "value3", + "expire" : 30000 + } +}</example> +</listitem> <listitem id="def_nginx_stream_server_zone"> <para>Stream Server Zone:</para> <list type="tag"> @@ -2903,7 +3191,7 @@ </listitem> <listitem id="def_nginx_stream_keyval_zone"> <para>Stream Keyval Shared Memory Zone:</para> -Contents of a stream keyval shared memory zone.<para>Example:</para> +Contents of a stream keyval shared memory zone when using the GET method.<para>Example:</para> <example> { "key1" : "value1", @@ -2911,6 +3199,20 @@ "key3" : "value3" }</example> </listitem> +<listitem id="def_nginx_stream_keyval_zone_post_patch"> +<para>Stream Keyval Shared Memory Zone:</para> +Contents of a stream keyval shared memory zone +when using the POST or PATCH methods.<para>Example:</para> +<example> +{ + "key1" : "value1", + "key2" : "value2", + "key3" : { + "value" : "value3", + "expire" : 30000 + } +}</example> +</listitem> <listitem id="def_nginx_stream_zone_sync"> <para>Stream Zone Sync Node:</para> <list type="tag"> @@ -2995,6 +3297,111 @@ </tag-desc> </list> </listitem> +<listitem id="def_nginx_resolver_zone"> +<para>Resolver Zone:</para> +Statistics of DNS requests and responses per particular +<link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone">resolver zone</link>.<list type="tag"> +<tag-name> +<literal>requests</literal></tag-name> +<tag-desc> +<list type="tag"> +<tag-name> +<literal>name</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of requests to resolve names to addresses. +</tag-desc> +<tag-name> +<literal>srv</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of requests to resolve SRV records. +</tag-desc> +<tag-name> +<literal>addr</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of requests to resolve addresses to names. +</tag-desc> +</list> +</tag-desc> +<tag-name> +<literal>responses</literal></tag-name> +<tag-desc> +<list type="tag"> +<tag-name> +<literal>noerror</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of successful responses. +</tag-desc> +<tag-name> +<literal>formerr</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of FORMERR (<literal>Format error</literal>) responses. +</tag-desc> +<tag-name> +<literal>servfail</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of SERVFAIL (<literal>Server failure</literal>) responses. +</tag-desc> +<tag-name> +<literal>nxdomain</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of NXDOMAIN (<literal>Host not found</literal>) responses. +</tag-desc> +<tag-name> +<literal>notimp</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of NOTIMP (<literal>Unimplemented</literal>) responses. +</tag-desc> +<tag-name> +<literal>refused</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of REFUSED (<literal>Operation refused</literal>) responses. +</tag-desc> +<tag-name> +<literal>timedout</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of timed out requests. +</tag-desc> +<tag-name> +<literal>unknown</literal> (<literal>integer</literal>) +</tag-name> +<tag-desc> +The total number of requests completed with an unknown error. +</tag-desc> +</list> +</tag-desc> +</list> +<para>Example:</para> +<example> +{ + "resolver_zone1" : { + "requests" : { + "name" : 25460, + "srv" : 130, + "addr" : 2580 + }, + "responses" : { + "noerror" : 26499, + "formerr" : 0, + "servfail" : 3, + "nxdomain" : 0, + "notimp" : 0, + "refused" : 0, + "timedout" : 243, + "unknown" : 478 + } + } +}</example> +</listitem> <listitem id="def_nginx_error"> <para>Error:</para> nginx error object.<list type="tag">
--- a/xml/en/docs/http/ngx_http_api_module_head.xml Thu Aug 22 23:00:31 2019 +0300 +++ b/xml/en/docs/http/ngx_http_api_module_head.xml Mon Sep 02 14:12:20 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/4/ -http://127.0.0.1/api/4/nginx -http://127.0.0.1/api/4/connections -http://127.0.0.1/api/4/http/requests -http://127.0.0.1/api/4/http/server_zones/server_backend -http://127.0.0.1/api/4/http/caches/cache_backend -http://127.0.0.1/api/4/http/upstreams/backend -http://127.0.0.1/api/4/http/upstreams/backend/servers/ -http://127.0.0.1/api/4/http/upstreams/backend/servers/1 -http://127.0.0.1/api/4/http/keyvals/one?key=arg1 -http://127.0.0.1/api/4/stream/ -http://127.0.0.1/api/4/stream/server_zones/server_backend -http://127.0.0.1/api/4/stream/upstreams/ -http://127.0.0.1/api/4/stream/upstreams/backend -http://127.0.0.1/api/4/stream/upstreams/backend/servers/1 +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 </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>4</literal>”. +The current API version is “<literal>5</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/4/nginx?fields=version,build +http://127.0.0.1/api/5/nginx?fields=version,build </example> </para> @@ -164,6 +164,8 @@ <syntax><value>zone</value></syntax> <default/> <context>server</context> +<context>location</context> +<context>if in location</context> <appeared-in>1.13.12</appeared-in> <para> @@ -175,6 +177,18 @@ Several servers may share the same zone. </para> +<para id="status_zone_location"> +Starting from 1.17.0, status information can be collected +per <link doc="ngx_http_core_module.xml" id="location"/>. +The special value <literal>off</literal> disables statistics collection +in nested location blocks. +Note that the statistics is collected +in the context of a location where processing ends. +It may be different from the original location, if an +<link doc="ngx_http_core_module.xml" id="internal">internal +redirect</link> happens during request processing. +</para> + </directive> </section> @@ -185,6 +199,24 @@ <list type="bullet"> <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 +<link id="patchHttpKeyvalZoneKeyValue">changed</link> +since <link id="api_version">version</link> 5. +</listitem> + +<listitem> +The <link id="resolvers_">/resolvers/</link> data +were added in <link id="api_version">version</link> 5. +</listitem> + +<listitem> +The <link id="http_location_zones_">/http/location_zones/</link> data +were added in <link id="api_version">version</link> 5. +</listitem> + +<listitem> The <literal>path</literal> and <literal>method</literal> fields of <link id="def_nginx_error">nginx error object</link> were removed in <link id="api_version">version</link> 4.
--- a/xml/en/docs/http/ngx_http_auth_jwt_module.xml Thu Aug 22 23:00:31 2019 +0300 +++ b/xml/en/docs/http/ngx_http_auth_jwt_module.xml Mon Sep 02 14:12:20 2019 +0300 @@ -9,7 +9,7 @@ <module name="Module ngx_http_auth_jwt_module" link="/en/docs/http/ngx_http_auth_jwt_module.html" lang="en" - rev="9"> + rev="10"> <section id="summary"> @@ -140,12 +140,8 @@ Name matching starts from the top level of the JSON tree. For arrays, the variable keeps a list of array elements separated by commas. <example> -location / { - auth_jwt "closed site"; - auth_jwt_key_file conf/keys.json; - auth_jwt_claim_set $email info e-mail; - auth_jwt_claim_set $job info "job title"; -} +auth_jwt_claim_set $email info e-mail; +auth_jwt_claim_set $job info "job title"; </example> <note> Prior to version 1.13.7, only one key name could be specified,
--- a/xml/en/docs/http/ngx_http_core_module.xml Thu Aug 22 23:00:31 2019 +0300 +++ b/xml/en/docs/http/ngx_http_core_module.xml Mon Sep 02 14:12:20 2019 +0300 @@ -10,7 +10,7 @@ <module name="Module ngx_http_core_module" link="/en/docs/http/ngx_http_core_module.html" lang="en" - rev="84"> + rev="85"> <section id="directives" name="Directives"> @@ -2108,7 +2108,8 @@ <syntax> <value>address</value> ... [<literal>valid</literal>=<value>time</value>] - [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]</syntax> + [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>] + [<literal>status_zone</literal>=<value>zone</value>]</syntax> <default/> <context>http</context> <context>server</context> @@ -2151,6 +2152,16 @@ </note> </para> +<para id="resolver_status_zone"> +The optional <literal>status_zone</literal> parameter (1.17.1) +enables +<link doc="ngx_http_api_module.xml" id="resolvers_">collection</link> +of DNS server statistics of requests and responses +in the specified <value>zone</value>. +The parameter is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</para> + </directive>
--- a/xml/en/docs/http/ngx_http_keyval_module.xml Thu Aug 22 23:00:31 2019 +0300 +++ b/xml/en/docs/http/ngx_http_keyval_module.xml Mon Sep 02 14:12:20 2019 +0300 @@ -9,7 +9,7 @@ <module name="Module ngx_http_keyval_module" link="/en/docs/http/ngx_http_keyval_module.html" lang="en" - rev="4"> + rev="5"> <section id="summary"> @@ -81,6 +81,7 @@ <literal>zone</literal>=<value>name</value>:<value>size</value> [<literal>state</literal>=<value>file</value>] [<literal>timeout</literal>=<value>time</value>] + [<literal>type</literal>=<literal>string</literal>|<literal>ip</literal>] [<literal>sync</literal>]</syntax> <default/> <context>http</context> @@ -103,6 +104,18 @@ the time after which key-value pairs are removed from the zone. </para> +<para id="keyval_type"> +The optional <literal>type</literal> parameter (1.17.1) specifies +the type of the key: +a <literal>string</literal> (default) or <literal>ip</literal>. +For the <literal>ip</literal> type, +the key must be the textual representation of an IP address +specified in CIDR notation. +In this case, +an additional index optimized for matching IP addresses and networks is used +in evaluating a variable. +</para> + <para id="keyval_sync"> The optional <literal>sync</literal> parameter (1.15.0) enables <link doc="../stream/ngx_stream_zone_sync_module.xml" id="zone_sync">synchronization</link>
--- a/xml/en/docs/stream/ngx_stream_keyval_module.xml Thu Aug 22 23:00:31 2019 +0300 +++ b/xml/en/docs/stream/ngx_stream_keyval_module.xml Mon Sep 02 14:12:20 2019 +0300 @@ -9,7 +9,7 @@ <module name="Module ngx_stream_keyval_module" link="/en/docs/stream/ngx_stream_keyval_module.html" lang="en" - rev="4"> + rev="5"> <section id="summary"> @@ -87,6 +87,7 @@ <literal>zone</literal>=<value>name</value>:<value>size</value> [<literal>state</literal>=<value>file</value>] [<literal>timeout</literal>=<value>time</value>] + [<literal>type</literal>=<literal>string</literal>|<literal>ip</literal>] [<literal>sync</literal>]</syntax> <default/> <context>stream</context> @@ -109,6 +110,18 @@ the time after which key-value pairs are removed from the zone. </para> +<para id="keyval_type"> +The optional <literal>type</literal> parameter (1.17.1) specifies +the type of the key: +a <literal>string</literal> (default) or <literal>ip</literal>. +For the <literal>ip</literal> type, +the key must be the textual representation of an IP address +specified in CIDR notation. +In this case, +an additional index optimized for matching IP addresses and networks is used +in evaluating a variable. +</para> + <para id="keyval_sync"> The optional <literal>sync</literal> parameter (1.15.0) enables <link doc="ngx_stream_zone_sync_module.xml" id="zone_sync">synchronization</link>
--- a/xml/ru/docs/http/ngx_http_auth_jwt_module.xml Thu Aug 22 23:00:31 2019 +0300 +++ b/xml/ru/docs/http/ngx_http_auth_jwt_module.xml Mon Sep 02 14:12:20 2019 +0300 @@ -9,7 +9,7 @@ <module name="Модуль ngx_http_auth_jwt_module" link="/ru/docs/http/ngx_http_auth_jwt_module.html" lang="ru" - rev="9"> + rev="10"> <section id="summary"> @@ -138,12 +138,8 @@ Сопоставление имён начинается с верхнего уровня дерева JSON. Для массива переменная хранит список его элементов, разделяемых запятыми. <example> -location / { - auth_jwt "closed site"; - auth_jwt_key_file conf/keys.json; - auth_jwt_claim_set $email info e-mail; - auth_jwt_claim_set $job info "job title"; -} +auth_jwt_claim_set $email info e-mail; +auth_jwt_claim_set $job info "job title"; </example> <note> До версии 1.13.7 можно было указать лишь одно имя,
--- a/xml/ru/docs/http/ngx_http_core_module.xml Thu Aug 22 23:00:31 2019 +0300 +++ b/xml/ru/docs/http/ngx_http_core_module.xml Mon Sep 02 14:12:20 2019 +0300 @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_core_module" link="/ru/docs/http/ngx_http_core_module.html" lang="ru" - rev="84"> + rev="85"> <section id="directives" name="Директивы"> @@ -2106,7 +2106,8 @@ <syntax> <value>адрес</value> ... [<literal>valid</literal>=<value>время</value>] - [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]</syntax> + [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>] + [<literal>status_zone</literal>=<value>зона</value>]</syntax> <default/> <context>http</context> <context>server</context> @@ -2151,6 +2152,16 @@ </note> </para> +<para id="resolver_status_zone"> +Необязательный параметр <literal>status_zone</literal> (1.17.1) +включает +<link doc="ngx_http_api_module.xml" id="resolvers_">сбор информации</link> +о запросах и ответах сервера DNS +в указанной <value>зоне</value>. +Параметр доступен как часть +<commercial_version>коммерческой подписки</commercial_version>. +</para> + </directive>
--- a/yaml/nginx_api.yaml Thu Aug 22 23:00:31 2019 +0300 +++ b/yaml/nginx_api.yaml Mon Sep 02 14:12:20 2019 +0300 @@ -1,6 +1,6 @@ swagger: '2.0' info: - version: '4.0' + version: '5.0' title: NGINX Plus REST API description: NGINX Plus REST [API](https://nginx.org/en/docs/http/ngx_http_api_module.html) @@ -9,23 +9,25 @@ key-value pairs management for [http](https://nginx.org/en/docs/http/ngx_http_keyval_module.html) and [stream](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html). -basePath: /api/4 +basePath: /api/5 tags: - name: General Info - name: Processes - name: Connections + - name: Slabs + - name: Resolvers - name: SSL - - name: Slabs - name: HTTP - name: HTTP Requests + - name: HTTP Server Zones + - name: HTTP Location Zones - name: HTTP Caches - - name: HTTP Server Zones + - name: HTTP Keyvals - name: HTTP Upstreams - - name: HTTP Keyvals - name: Stream - name: Stream Server Zones + - name: Stream Keyvals - name: Stream Upstreams - - name: Stream Keyvals - name: Stream Zone Sync - name: Method GET - name: Method POST @@ -128,36 +130,6 @@ responses: '204': description: Success - /ssl: - get: - tags: - - SSL - - Method GET - summary: Return SSL statistics - description: Returns SSL statistics. - operationId: getSsl - produces: - - application/json - responses: - '200': - description: Success - schema: - $ref: '#/definitions/NginxSSLObject' - parameters: - - in: query - name: fields - type: string - description: Limits which fields of SSL statistics will be output. - delete: - tags: - - SSL - - Method DELETE - summary: Reset SSL statistics - description: Resets counters of SSL handshakes and session reuses. - operationId: deleteSslStat - responses: - '204': - description: Success /slabs/: get: tags: @@ -175,7 +147,7 @@ type: string description: Limits which fields of slab zones will be output. If the “<literal>fields</literal>” value is empty, - then only zone names are output. + then only zone names will be output. responses: '200': description: Success @@ -298,7 +270,7 @@ type: string description: Limits which fields of server zones will be output. If the “<literal>fields</literal>” value is empty, - then only server zone names are output. + then only server zone names will be output. responses: '200': description: Success @@ -353,6 +325,79 @@ description: Method disabled (*MethodDisabled*) schema: $ref: '#/definitions/NginxError' + /http/location_zones/: + get: + tags: + - HTTP Location Zones + - Method GET + summary: Return status of all HTTP location zones + description: Returns status information for each HTTP + [location zone](https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone_location). + operationId: getHttpLocationZones + produces: + - application/json + parameters: + - in: query + name: fields + type: string + description: Limits which fields of location zones will be output. + If the “<literal>fields</literal>” value is empty, + then only zone names will be output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPLocationZonesMap' + '/http/location_zones/{httpLocationZoneName}': + parameters: + - name: httpLocationZoneName + in: path + description: The name of an HTTP [location zone](https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone_location). + type: string + required: true + get: + tags: + - HTTP Location Zones + - Method GET + summary: Return status of an HTTP location zone + description: Returns status of a particular + HTTP [location zone](https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone_location). + operationId: getHttpLocationZone + produces: + - application/json + parameters: + - name: fields + in: query + type: string + description: Limits which fields of the location zone will be output. + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxHTTPLocationZone' + '404': + description: Location zone not found (*LocationZoneNotFound*) + schema: + $ref: '#/definitions/NginxError' + delete: + tags: + - HTTP Location Zones + - Method DELETE + summary: Reset statistics for a location zone. + description: Resets statistics of accepted and discarded requests, responses, + received and sent bytes in a particular location zone. + operationId: deleteHttpLocationZoneStat + responses: + '204': + description: Success + '404': + description: Location zone not found (*LocationZoneNotFound*) + schema: + $ref: '#/definitions/NginxError' + '405': + description: Method disabled (*MethodDisabled*) + schema: + $ref: '#/definitions/NginxError' /http/caches/: get: tags: @@ -371,7 +416,7 @@ type: string description: Limits which fields of cache zones will be output. If the “<literal>fields</literal>” value is empty, - then only names of cache zones are output. + then only names of cache zones will be output. responses: '200': description: Success @@ -442,7 +487,7 @@ 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 are output. + only names of upstreams will be output. responses: '200': description: Success @@ -743,7 +788,7 @@ in: query type: string description: If the “<literal>fields</literal>” value is empty, - then only HTTP keyval zone names are output. + then only HTTP keyval zone names will be output. responses: '200': description: Success @@ -800,17 +845,25 @@ description: A key-value pair is specified in the JSON format. Several key-value pairs can be entered if the HTTP keyval shared memory zone is empty. + Expiration time in milliseconds can be specified for a key-value pair + with the *expire* parameter + which overrides the [*timeout*](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_timeout) + parameter of the + <a href="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">keyval_zone</a> + directive. required: true schema: - $ref: '#/definitions/NginxHTTPKeyvalZone' + $ref: '#/definitions/NginxHTTPKeyvalZonePostPatch' responses: '201': description: Created '400': description: | - Key required (*KeyvalFormatError*), - only one key can be added (*KeyvalFormatError*), - nested object or list (*KeyvalFormatError*) + Invalid JSON (*KeyvalFormatError*), + invalid key format (*KeyvalFormatError*), + key required (*KeyvalFormatError*), + keyval timeout is not enabled (*KeyvalFormatError*), + only one key can be added (*KeyvalFormatError*) schema: $ref: '#/definitions/NginxError' '404': @@ -834,12 +887,19 @@ - HTTP Keyvals - Method PATCH summary: Modify a key-value or delete a key - description: Changes the value of the selected key in the key-value pair - or deletes a key by setting the key value to <literal>null</literal>. + description: Changes the value of the selected key in the key-value pair, + deletes a key by setting the key value to <literal>null</literal>, + changes expiration time of a key-value pair. If <a href="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</a> of keyval zones in a cluster is enabled, deletes a key only on a target cluster node. + Expiration time in milliseconds can be specified for a key-value pair + with the *expire* parameter + which overrides the [*timeout*](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_timeout) + parameter of the + <a href="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">keyval_zone</a> + directive. operationId: patchHttpKeyvalZoneKeyValue produces: - application/json @@ -849,15 +909,16 @@ description: A new value for the key is specified in the JSON format. required: true schema: - $ref: '#/definitions/NginxHTTPKeyvalZone' + $ref: '#/definitions/NginxHTTPKeyvalZonePostPatch' responses: '204': description: Success '400': description: | - Key required (*KeyvalFormatError*), - only one key can be updated (*KeyvalFormatError*), - nested object or list (*KeyvalFormatError*) + Invalid JSON (*KeyvalFormatError*), + key required (*KeyvalFormatError*), + keyval timeout is not enabled (*KeyvalFormatError*), + only one key can be updated (*KeyvalFormatError*) schema: $ref: '#/definitions/NginxError' '404': @@ -928,7 +989,7 @@ type: string description: Limits which fields of server zones will be output. If the “<literal>fields</literal>” value is empty, - then only server zone names are output. + then only server zone names will be output. responses: '200': description: Success @@ -1002,7 +1063,7 @@ 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 are output. + only names of upstreams will be output. responses: '200': description: Success @@ -1307,7 +1368,7 @@ in: query type: string description: If the “<literal>fields</literal>” value is empty, - then only stream keyval zone names are output. + then only stream keyval zone names will be output. responses: '200': description: Success @@ -1364,17 +1425,25 @@ description: A key-value pair is specified in the JSON format. Several key-value pairs can be entered if the stream keyval shared memory zone is empty. + Expiration time in milliseconds can be specified for a key-value pair + with the *expire* parameter + which overrides the [*timeout*](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_timeout) + parameter of the + <a href="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">keyval_zone</a> + directive. required: true schema: - $ref: '#/definitions/NginxStreamKeyvalZone' + $ref: '#/definitions/NginxStreamKeyvalZonePostPatch' responses: '201': description: Created '400': description: | - Key required (*KeyvalFormatError*), - only one key can be added (*KeyvalFormatError*), - nested object or list (*KeyvalFormatError*) + Invalid JSON (*KeyvalFormatError*), + invalid key format (*KeyvalFormatError*), + key required (*KeyvalFormatError*), + keyval timeout is not enabled (*KeyvalFormatError*), + only one key can be added (*KeyvalFormatError*) schema: $ref: '#/definitions/NginxError' '404': @@ -1399,12 +1468,19 @@ - Stream Keyvals - Method PATCH summary: Modify a key-value or delete a key - description: Changes the value of the selected key in the key-value pair - or deletes a key by setting the key value to <literal>null</literal>. + description: Changes the value of the selected key in the key-value pair, + deletes a key by setting the key value to <literal>null</literal>, + changes expiration time of a key-value pair. If <a href="https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync">synchronization</a> of keyval zones in a cluster is enabled, deletes a key only on a target cluster node. + Expiration time is specified in milliseconds + with the *expire* parameter + which overrides the [*timeout*](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_timeout) + parameter of the + <a href="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">keyval_zone</a> + directive. operationId: patchStreamKeyvalZoneKeyValue produces: - application/json @@ -1414,15 +1490,16 @@ description: A new value for the key is specified in the JSON format. required: true schema: - $ref: '#/definitions/NginxStreamKeyvalZone' + $ref: '#/definitions/NginxStreamKeyvalZonePostPatch' responses: '204': description: Success '400': description: | - Key required (*KeyvalFormatError*), - only one key can be updated (*KeyvalFormatError*), - nested object or list (*KeyvalFormatError*) + Invalid JSON (*KeyvalFormatError*), + key required (*KeyvalFormatError*), + keyval timeout is not enabled (*KeyvalFormatError*), + only one key can be updated (*KeyvalFormatError*) schema: $ref: '#/definitions/NginxError' '404': @@ -1478,6 +1555,108 @@ description: Success schema: $ref: '#/definitions/NginxStreamZoneSync' + /resolvers/: + get: + tags: + - Resolvers + - Method GET + summary: Return status for all resolver zones + description: Returns status information for each + [resolver zone](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone). + operationId: getResolverZones + produces: + - application/json + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxResolverZonesMap' + parameters: + - in: query + name: fields + type: string + description: Limits which fields of resolvers statistics will be output. + '/resolvers/{resolverZoneName}': + parameters: + - name: resolverZoneName + in: path + description: The name of a resolver zone. + required: true + type: string + get: + tags: + - Resolvers + - Method GET + summary: Return statistics of a resolver zone + description: Returns statistics stored in a particular resolver + [zone](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone). + operationId: getResolverZone + produces: + - application/json + parameters: + - name: fields + in: query + type: string + description: Limits which fields of the resolver zone will be output + (requests, responses, or both). + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxResolverZone' + '404': + description: | + Resolver zone not found (*ResolverZoneNotFound*) + schema: + $ref: '#/definitions/NginxError' + delete: + tags: + - Resolvers + - Method DELETE + summary: Reset statistics for a resolver zone. + description: Resets statistics in a particular resolver zone. + operationId: deleteResolverZoneStat + responses: + '204': + description: Success + '404': + description: Resolver zone not found (*ResolverZoneNotFound*) + schema: + $ref: '#/definitions/NginxError' + '405': + description: Method disabled (*MethodDisabled*) + schema: + $ref: '#/definitions/NginxError' + /ssl: + get: + tags: + - SSL + - Method GET + summary: Return SSL statistics + description: Returns SSL statistics. + operationId: getSsl + produces: + - application/json + responses: + '200': + description: Success + schema: + $ref: '#/definitions/NginxSSLObject' + parameters: + - in: query + name: fields + type: string + description: Limits which fields of SSL statistics will be output. + delete: + tags: + - SSL + - Method DELETE + summary: Reset SSL statistics + description: Resets counters of SSL handshakes and session reuses. + operationId: deleteSslStat + responses: + '204': + description: Success ### ###DEFINITIONS ### @@ -1836,6 +2015,100 @@ example: processing: 1 requests: 706690 + responses: + 1xx: 0 + 2xx: 699482 + 3xx: 4522 + 4xx: 907 + 5xx: 266 + total: 705177 + discarded: 1513 + received: 172711587 + sent: 19415530115 + NginxHTTPLocationZonesMap: + title: HTTP Location Zones + description: | + Status data for all HTTP + <a href="https://nginx.org/en/docs/http/ngx_http_api_module.html#status_zone">location zones</a>. + type: object + additionalProperties: + $ref: '#/definitions/NginxHTTPLocationZone' + example: + site1: + requests: 736395 + responses: + 1xx: 0 + 2xx: 727290 + 3xx: 4614 + 4xx: 934 + 5xx: 1535 + total: 734373 + discarded: 2020 + received: 180157219 + sent: 20183175459 + site2: + requests: 185307 + responses: + 1xx: 0 + 2xx: 112674 + 3xx: 45383 + 4xx: 2504 + 5xx: 4419 + total: 164980 + discarded: 20326 + received: 51575327 + sent: 2983241510 + NginxHTTPLocationZone: + title: HTTP Location Zone + type: object + properties: + requests: + type: integer + description: The total number of client requests received from clients. + responses: + description: The total number of responses sent to clients and the + number of responses with status codes + “<code>1xx</code>”, “<code>2xx</code>”, “<code>3xx</code>”, + “<code>4xx</code>”, and “<code>5xx</code>”. + type: object + readOnly: true + properties: + 1xx: + type: integer + description: The number of responses with “<code>1xx</code>” status codes. + readOnly: true + 2xx: + type: integer + description: The number of responses with “<code>2xx</code>” status codes. + readOnly: true + 3xx: + type: integer + description: The number of responses with “<code>3xx</code>” status codes. + readOnly: true + 4xx: + type: integer + description: The number of responses with “<code>4xx</code>” status codes. + readOnly: true + 5xx: + type: integer + description: The number of responses with “<code>5xx</code>” status codes. + readOnly: true + total: + type: integer + description: The total number of responses sent to clients. + readOnly: true + discarded: + type: integer + description: The total number of + requests completed without sending a response. + received: + type: integer + description: The total number of bytes received from clients. + sent: + type: integer + description: The total number of bytes sent to clients. + example: + requests: 706690 responses: 1xx: 0 2xx: 699482 @@ -2602,12 +2875,25 @@ NginxHTTPKeyvalZone: title: HTTP Keyval Shared Memory Zone description: | - Contents of an HTTP keyval shared memory zone. + Contents of an HTTP keyval shared memory zone + when using the GET method. type: object example: key1: value1 key2: value2 key3: value3 + NginxHTTPKeyvalZonePostPatch: + title: HTTP Keyval Shared Memory Zone + description: | + Contents of an HTTP keyval shared memory zone + when using the POST or PATCH methods. + type: object + example: + key1: value1 + key2: value2 + key3: + value: value3 + expire: 30000 NginxStreamServerZonesMap: title: Stream Server Zones description: | @@ -3140,12 +3426,24 @@ NginxStreamKeyvalZone: title: Stream Keyval Shared Memory Zone description: | - Contents of a stream keyval shared memory zone. + Contents of a stream keyval shared memory zone when using the GET method. type: object example: key1: value1 key2: value2 key3: value3 + NginxStreamKeyvalZonePostPatch: + title: Stream Keyval Shared Memory Zone + description: | + Contents of a stream keyval shared memory zone + when using the POST or PATCH methods. + type: object + example: + key1: value1 + key2: value2 + key3: + value: value3 + expire: 30000 NginxStreamZoneSync: title: Stream Zone Sync Node type: object @@ -3200,6 +3498,126 @@ records_total: type: integer description: The total number of records stored in the shared memory zone. + NginxResolverZonesMap: + title: Resolver Zones + description: | + Status data for all + <a href="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone">resolver zones</a>. + type: object + additionalProperties: + $ref: '#/definitions/NginxResolverZone' + example: + resolver_zone1: + requests: + name: 25460 + srv: 130 + addr: 2580 + responses: + noerror: 26499 + formerr: 0 + servfail: 3 + nxdomain: 0 + notimp: 0 + refused: 0 + timedout: 243 + unknown: 478 + resolver_zone2: + requests: + name: 325460 + srv: 1130 + addr: 12580 + responses: + noerror: 226499 + formerr: 0 + servfail: 283 + nxdomain: 0 + notimp: 0 + refused: 0 + timedout: 743 + unknown: 1478 + NginxResolverZone: + title: Resolver Zone + description: | + Statistics of DNS requests and responses per particular + <a href="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_status_zone">resolver zone</a>. + type: object + properties: + requests: + type: object + readOnly: true + properties: + name: + type: integer + description: The total number of requests + to resolve names to addresses. + readOnly: true + srv: + type: integer + description: The total number of requests + to resolve SRV records. + readOnly: true + addr: + type: integer + description: The total number of requests + to resolve addresses to names. + readOnly: true + responses: + type: object + readOnly: true + properties: + noerror: + type: integer + description: The total number of successful responses. + readOnly: true + formerr: + type: integer + description: The total number of + FORMERR (<literal>Format error</literal>) responses. + readOnly: true + servfail: + type: integer + description: The total number of + SERVFAIL (<literal>Server failure</literal>) responses. + readOnly: true + nxdomain: + type: integer + description: The total number of + NXDOMAIN (<literal>Host not found</literal>) responses. + readOnly: true + notimp: + type: integer + description: The total number of + NOTIMP (<literal>Unimplemented</literal>) responses. + readOnly: true + refused: + type: integer + description: The total number of + REFUSED (<literal>Operation refused</literal>) responses. + readOnly: true + timedout: + type: integer + description: The total number of timed out requests. + readOnly: true + unknown: + type: integer + description: The total number of requests + completed with an unknown error. + readOnly: true + example: + resolver_zone1: + requests: + name: 25460 + srv: 130 + addr: 2580 + responses: + noerror: 26499 + formerr: 0 + servfail: 3 + nxdomain: 0 + notimp: 0 + refused: 0 + timedout: 243 + unknown: 478 NginxError: title: Error description: |
--- a/yaml/yaml2xml.py Thu Aug 22 23:00:31 2019 +0300 +++ b/yaml/yaml2xml.py Mon Sep 02 14:12:20 2019 +0300 @@ -44,7 +44,7 @@ def pretty_endpoint(ep): - return ep.replace('/',' ').replace('_',' ') + return ep.replace('/slabs/','slabs').replace('/resolvers/','resolvers').replace('/http/','HTTP ').replace('/stream/','stream ').replace('s/','s').replace('_',' ') # human-readable html element id based on path