Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_api_module.xml @ 2082:fee7627f6a5a

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, 11 Dec 2017 12:13:09 +0300
parents 116994597b0e
children a645aa9f2ebf
comparison
equal deleted inserted replaced
2081:f29bd40e9a62 2082:fee7627f6a5a
95 status_zone server_backend; 95 status_zone server_backend;
96 health_check; 96 health_check;
97 } 97 }
98 } 98 }
99 </example> 99 </example>
100 All API requests include a supported API version in the URI. 100 All API requests include
101 a supported API <link id="api_version">version</link> in the URI.
101 Examples of API requests with this configuration: 102 Examples of API requests with this configuration:
102 <example> 103 <example>
103 http://127.0.0.1/api/1/ 104 http://127.0.0.1/api/2/
104 http://127.0.0.1/api/1/nginx 105 http://127.0.0.1/api/2/nginx
105 http://127.0.0.1/api/1/connections 106 http://127.0.0.1/api/2/connections
106 http://127.0.0.1/api/1/http/requests 107 http://127.0.0.1/api/2/http/requests
107 http://127.0.0.1/api/1/http/server_zones/server_backend 108 http://127.0.0.1/api/2/http/server_zones/server_backend
108 http://127.0.0.1/api/1/http/caches/cache_backend 109 http://127.0.0.1/api/2/http/caches/cache_backend
109 http://127.0.0.1/api/1/http/upstreams/backend 110 http://127.0.0.1/api/2/http/upstreams/backend
110 http://127.0.0.1/api/1/http/upstreams/backend/servers/ 111 http://127.0.0.1/api/2/http/upstreams/backend/servers/
111 http://127.0.0.1/api/1/http/upstreams/backend/servers/1 112 http://127.0.0.1/api/2/http/upstreams/backend/servers/1
112 http://127.0.0.1/api/1/http/keyvals/one?key=arg1 113 http://127.0.0.1/api/2/http/keyvals/one?key=arg1
113 http://127.0.0.1/api/1/stream/ 114 http://127.0.0.1/api/2/stream/
114 http://127.0.0.1/api/1/stream/server_zones/server_backend 115 http://127.0.0.1/api/2/stream/server_zones/server_backend
115 http://127.0.0.1/api/1/stream/upstreams/ 116 http://127.0.0.1/api/2/stream/upstreams/
116 http://127.0.0.1/api/1/stream/upstreams/backend 117 http://127.0.0.1/api/2/stream/upstreams/backend
117 http://127.0.0.1/api/1/stream/upstreams/backend/servers/1 118 http://127.0.0.1/api/2/stream/upstreams/backend/servers/1
118 </example> 119 </example>
119 </para> 120 </para>
120 121
121 </section> 122 </section>
122 123
139 The <literal>write</literal> parameter determines whether the API 140 The <literal>write</literal> parameter determines whether the API
140 is read-only or read-write. 141 is read-only or read-write.
141 By default, the API is read-only. 142 By default, the API is read-only.
142 </para> 143 </para>
143 144
144 <para> 145 <para id="api_version">
145 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.
146 If the request URI equals the location prefix, 147 If the request URI equals the location prefix,
147 the list of supported API versions is returned. 148 the list of supported API versions is returned.
148 The current and the only API version is “<literal>1</literal>”. 149 The current API version is “<literal>2</literal>”.
149 </para> 150 </para>
150 151
151 <para> 152 <para>
152 The optional “<literal>fields</literal>” argument in the request line 153 The optional “<literal>fields</literal>” argument in the request line
153 specifies which fields of the requested objects will be output: 154 specifies which fields of the requested objects will be output:
154 <example> 155 <example>
155 http://127.0.0.1/api/1/nginx?fields=version,build 156 http://127.0.0.1/api/2/nginx?fields=version,build
156 </example> 157 </example>
157 </para> 158 </para>
158 159
159 </directive> 160 </directive>
161
162 </section>
163
164 <section id="compatibility" name="Compatibility">
165
166 <para>
167 <list type="bullet">
168
169 <listitem>
170 The <link id="def_nginx_http_upstream_conf_server">drain</link> parameter
171 was added in <link id="api_version">version</link> 2.
172 </listitem>
173
174 <listitem>
175 The <link id="stream_keyvals_">/stream/keyvals/</link> data
176 were added in <link id="api_version">version</link> 2.
177 </listitem>
178
179 </list>
180 </para>
160 181
161 </section> 182 </section>
162 <section id="endpoints" name="Endpoints"> 183 <section id="endpoints" name="Endpoints">
163 <para> 184 <para>
164 <list type="tag"> 185 <list type="tag">
824 </tag-name> 845 </tag-name>
825 <tag-desc> 846 <tag-desc>
826 <para>Supported methods:</para> 847 <para>Supported methods:</para>
827 <list type="bullet" compact="yes"> 848 <list type="bullet" compact="yes">
828 <listitem id="getHttpKeyvalZones"> 849 <listitem id="getHttpKeyvalZones">
829 <literal>GET</literal> - Return key-value pairs from all keyval zones 850 <literal>GET</literal> - Return key-value pairs from all HTTP keyval zones
830 <para>Returns key-value pairs for each keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para> 851 <para>Returns key-value pairs for each HTTP keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para>
831 <para> 852 <para>
832 Request parameters: 853 Request parameters:
833 <list type="tag"> 854 <list type="tag">
834 <tag-name><literal>fields</literal> 855 <tag-name><literal>fields</literal>
835 (<literal>string</literal>, optional)</tag-name> 856 (<literal>string</literal>, optional)</tag-name>
836 <tag-desc> 857 <tag-desc>
837 If the “<literal>fields</literal>” value is empty, then only keyval zone names are output.</tag-desc> 858 If the “<literal>fields</literal>” value is empty, then only HTTP keyval zone names are output.</tag-desc>
838 </list> 859 </list>
839 </para> 860 </para>
840 <para> 861 <para>
841 Possible responses: 862 Possible responses:
842 </para> 863 </para>
843 <list type="bullet"> 864 <list type="bullet">
844 <listitem>200 - Success, returns a collection of "<link id="def_nginx_http_keyval_zone">Keyval Shared Memory Zone</link>" objects for all http keyvals </listitem> 865 <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>
845 </list> 866 </list>
846 </listitem> 867 </listitem>
847 </list> 868 </list>
848 </tag-desc> 869 </tag-desc>
849 <tag-name id="http_keyvals_http_keyval_zone_name" name="/http/keyvals/{httpKeyvalZoneName}"> 870 <tag-name id="http_keyvals_http_keyval_zone_name" name="/http/keyvals/{httpKeyvalZoneName}">
853 Parameters common for all methods: 874 Parameters common for all methods:
854 <list type="tag"> 875 <list type="tag">
855 <tag-name><literal>httpKeyvalZoneName</literal> 876 <tag-name><literal>httpKeyvalZoneName</literal>
856 (<literal>string</literal>, required)</tag-name> 877 (<literal>string</literal>, required)</tag-name>
857 <tag-desc> 878 <tag-desc>
858 The name of a keyval shared memory zone.</tag-desc> 879 The name of an HTTP keyval shared memory zone.</tag-desc>
859 </list> 880 </list>
860 <para>Supported methods:</para> 881 <para>Supported methods:</para>
861 <list type="bullet" compact="yes"> 882 <list type="bullet" compact="yes">
862 <listitem id="getHttpKeyvalZoneKeysValues"> 883 <listitem id="getHttpKeyvalZoneKeysValues">
863 <literal>GET</literal> - Return key-value pairs from a keyval zone 884 <literal>GET</literal> - Return key-value pairs from an HTTP keyval zone
864 <para>Returns key-value pairs stored in a particular keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para> 885 <para>Returns key-value pairs stored in a particular HTTP keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para>
865 <para> 886 <para>
866 Request parameters: 887 Request parameters:
867 <list type="tag"> 888 <list type="tag">
868 <tag-name><literal>key</literal> 889 <tag-name><literal>key</literal>
869 (<literal>string</literal>, optional)</tag-name> 890 (<literal>string</literal>, optional)</tag-name>
870 <tag-desc> 891 <tag-desc>
871 Get a particular key-value pair from the keyval zone.</tag-desc> 892 Get a particular key-value pair from the HTTP keyval zone.</tag-desc>
872 </list> 893 </list>
873 </para> 894 </para>
874 <para> 895 <para>
875 Possible responses: 896 Possible responses:
876 </para> 897 </para>
877 <list type="bullet"> 898 <list type="bullet">
878 <listitem>200 - Success, returns <link id="def_nginx_http_keyval_zone">Keyval Shared Memory Zone</link></listitem> 899 <listitem>200 - Success, returns <link id="def_nginx_http_keyval_zone">HTTP Keyval Shared Memory Zone</link></listitem>
879 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), 900 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>),
880 keyval key not found (<literal>KeyvalKeyNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> 901 keyval key not found (<literal>KeyvalKeyNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem>
881 </list> 902 </list>
882 </listitem> 903 </listitem>
883 <listitem id="postHttpKeyvalZoneData"> 904 <listitem id="postHttpKeyvalZoneData">
884 <literal>POST</literal> - Add a key-value pair to the keyval zone 905 <literal>POST</literal> - Add a key-value pair to the HTTP keyval zone
885 <para>Adds a new key-value pair to the keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>. Several key-value pairs can be entered if the keyval shared memory zone is empty.</para> 906 <para>Adds a new key-value pair to the HTTP keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>. Several key-value pairs can be entered if the HTTP keyval shared memory zone is empty.</para>
886 <para> 907 <para>
887 Request parameters: 908 Request parameters:
888 <list type="tag"> 909 <list type="tag">
889 <tag-name><literal>Key-value</literal> 910 <tag-name><literal>Key-value</literal>
890 (<link id="def_nginx_http_keyval_zone">Keyval Shared Memory Zone</link>, required)</tag-name> 911 (<link id="def_nginx_http_keyval_zone">HTTP Keyval Shared Memory Zone</link>, required)</tag-name>
891 <tag-desc> 912 <tag-desc>
892 A key-value pair is specified in the JSON format. Several key-value pairs can be entered if the keyval shared memory zone is empty.</tag-desc> 913 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>
893 </list> 914 </list>
894 </para> 915 </para>
895 <para> 916 <para>
896 Possible responses: 917 Possible responses:
897 </para> 918 </para>
911 <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>.</para> 932 <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>.</para>
912 <para> 933 <para>
913 Request parameters: 934 Request parameters:
914 <list type="tag"> 935 <list type="tag">
915 <tag-name><literal>httpKeyvalZoneKeyValue</literal> 936 <tag-name><literal>httpKeyvalZoneKeyValue</literal>
916 (<link id="def_nginx_http_keyval_zone">Keyval Shared Memory Zone</link>, required)</tag-name> 937 (<link id="def_nginx_http_keyval_zone">HTTP Keyval Shared Memory Zone</link>, required)</tag-name>
917 <tag-desc> 938 <tag-desc>
918 A new value for the key is specified in the JSON format.</tag-desc> 939 A new value for the key is specified in the JSON format.</tag-desc>
919 </list> 940 </list>
920 </para> 941 </para>
921 <para> 942 <para>
931 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> 952 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
932 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> 953 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
933 </list> 954 </list>
934 </listitem> 955 </listitem>
935 <listitem id="deleteHttpKeyvalZoneData"> 956 <listitem id="deleteHttpKeyvalZoneData">
936 <literal>DELETE</literal> - Empty the keyval zone 957 <literal>DELETE</literal> - Empty the HTTP keyval zone
937 <para>Deletes all key-value pairs from the keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para> 958 <para>Deletes all key-value pairs from the HTTP keyval shared memory <link url="https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone">zone</link>.</para>
938 <para> 959 <para>
939 Possible responses: 960 Possible responses:
940 </para> 961 </para>
941 <list type="bullet"> 962 <list type="bullet">
942 <listitem>204 - Success</listitem> 963 <listitem>204 - Success</listitem>
1273 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), 1294 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>),
1274 invalid server ID (<literal>UpstreamBadServerId</literal>), 1295 invalid server ID (<literal>UpstreamBadServerId</literal>),
1275 server “<value>id</value>” not removable (<literal>UpstreamServerImmutable</literal>), returns <link id="def_nginx_error">Error</link></listitem> 1296 server “<value>id</value>” not removable (<literal>UpstreamServerImmutable</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1276 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), 1297 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>),
1277 server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), 1298 server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>),
1299 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1300 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1301 </list>
1302 </listitem>
1303 </list>
1304 </tag-desc>
1305 <tag-name id="stream_keyvals_" name="/stream/keyvals/">
1306 <literal>/stream/keyvals/</literal>
1307 </tag-name>
1308 <tag-desc>
1309 <para>Supported methods:</para>
1310 <list type="bullet" compact="yes">
1311 <listitem id="getStreamKeyvalZones">
1312 <literal>GET</literal> - Return key-value pairs from all stream keyval zones
1313 <para>Returns key-value pairs for each stream keyval shared memory <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">zone</link>.</para>
1314 <para>
1315 Request parameters:
1316 <list type="tag">
1317 <tag-name><literal>fields</literal>
1318 (<literal>string</literal>, optional)</tag-name>
1319 <tag-desc>
1320 If the “<literal>fields</literal>” value is empty, then only stream keyval zone names are output.</tag-desc>
1321 </list>
1322 </para>
1323 <para>
1324 Possible responses:
1325 </para>
1326 <list type="bullet">
1327 <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>
1328 <listitem>404 - <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1329 </list>
1330 </listitem>
1331 </list>
1332 </tag-desc>
1333 <tag-name id="stream_keyvals_stream_keyval_zone_name" name="/stream/keyvals/{streamKeyvalZoneName}">
1334 <literal>/stream/keyvals/{streamKeyvalZoneName}</literal>
1335 </tag-name>
1336 <tag-desc>
1337 Parameters common for all methods:
1338 <list type="tag">
1339 <tag-name><literal>streamKeyvalZoneName</literal>
1340 (<literal>string</literal>, required)</tag-name>
1341 <tag-desc>
1342 The name of a stream keyval shared memory zone.</tag-desc>
1343 </list>
1344 <para>Supported methods:</para>
1345 <list type="bullet" compact="yes">
1346 <listitem id="getStreamKeyvalZoneKeysValues">
1347 <literal>GET</literal> - Return key-value pairs from a stream keyval zone
1348 <para>Returns key-value pairs stored in a particular stream keyval shared memory <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">zone</link>.</para>
1349 <para>
1350 Request parameters:
1351 <list type="tag">
1352 <tag-name><literal>key</literal>
1353 (<literal>string</literal>, optional)</tag-name>
1354 <tag-desc>
1355 Get a particular key-value pair from the stream keyval zone.</tag-desc>
1356 </list>
1357 </para>
1358 <para>
1359 Possible responses:
1360 </para>
1361 <list type="bullet">
1362 <listitem>200 - Success, returns <link id="def_nginx_stream_keyval_zone">Stream Keyval Shared Memory Zone</link></listitem>
1363 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>),
1364 keyval key not found (<literal>KeyvalKeyNotFound</literal>),
1365 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1366 </list>
1367 </listitem>
1368 <listitem id="postStreamKeyvalZoneData">
1369 <literal>POST</literal> - Add a key-value pair to the stream keyval zone
1370 <para>Adds a new key-value pair to the stream keyval shared memory <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">zone</link>. Several key-value pairs can be entered if the stream keyval shared memory zone is empty.</para>
1371 <para>
1372 Request parameters:
1373 <list type="tag">
1374 <tag-name><literal>Key-value</literal>
1375 (<link id="def_nginx_stream_keyval_zone">Stream Keyval Shared Memory Zone</link>, required)</tag-name>
1376 <tag-desc>
1377 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>
1378 </list>
1379 </para>
1380 <para>
1381 Possible responses:
1382 </para>
1383 <list type="bullet">
1384 <listitem>201 - Created</listitem>
1385 <listitem>400 - Key required (<literal>KeyvalFormatError</literal>),
1386 only one key can be added (<literal>KeyvalFormatError</literal>),
1387 nested object or list (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1388 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>),
1389 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1390 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1391 <listitem>409 - Key already exists (<literal>KeyvalKeyExists</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1392 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1393 </list>
1394 </listitem>
1395 <listitem id="patchStreamKeyvalZoneKeyValue">
1396 <literal>PATCH</literal> - Modify a key-value or delete a key
1397 <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>.</para>
1398 <para>
1399 Request parameters:
1400 <list type="tag">
1401 <tag-name><literal>streamKeyvalZoneKeyValue</literal>
1402 (<link id="def_nginx_stream_keyval_zone">Stream Keyval Shared Memory Zone</link>, required)</tag-name>
1403 <tag-desc>
1404 A new value for the key is specified in the JSON format.</tag-desc>
1405 </list>
1406 </para>
1407 <para>
1408 Possible responses:
1409 </para>
1410 <list type="bullet">
1411 <listitem>204 - Success</listitem>
1412 <listitem>400 - Key required (<literal>KeyvalFormatError</literal>),
1413 only one key can be updated (<literal>KeyvalFormatError</literal>),
1414 nested object or list (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1415 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>),
1416 keyval key not found (<literal>KeyvalKeyNotFound</literal>),
1417 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1418 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1419 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1420 </list>
1421 </listitem>
1422 <listitem id="deleteStreamKeyvalZoneData">
1423 <literal>DELETE</literal> - Empty the stream keyval zone
1424 <para>Deletes all key-value pairs from the stream keyval shared memory <link url="https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone">zone</link>.</para>
1425 <para>
1426 Possible responses:
1427 </para>
1428 <list type="bullet">
1429 <listitem>204 - Success</listitem>
1430 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>),
1278 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem> 1431 <link url="https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream">stream</link> not configured (<literal>StreamNotConfigured</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1279 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> 1432 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1280 </list> 1433 </list>
1281 </listitem> 1434 </listitem>
1282 </list> 1435 </list>
2266 </tag-name> 2419 </tag-name>
2267 <tag-desc> 2420 <tag-desc>
2268 Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#down">down</link> parameter of the HTTP upstream server. 2421 Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#down">down</link> parameter of the HTTP upstream server.
2269 </tag-desc> 2422 </tag-desc>
2270 <tag-name> 2423 <tag-name>
2424 <literal>drain</literal> (<literal>boolean</literal>)
2425 </tag-name>
2426 <tag-desc>
2427 Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#drain">drain</link> parameter of the HTTP upstream server.
2428 </tag-desc>
2429 <tag-name>
2271 <literal>parent</literal> (<literal>string</literal>) 2430 <literal>parent</literal> (<literal>string</literal>)
2272 </tag-name> 2431 </tag-name>
2273 <tag-desc> 2432 <tag-desc>
2274 Parent server ID of the resolved server. The ID is assigned automatically and cannot be changed. 2433 Parent server ID of the resolved server. The ID is assigned automatically and cannot be changed.
2275 </tag-desc> 2434 </tag-desc>
2276 <tag-name> 2435 <tag-name>
2277 <literal>host</literal> (<literal>string</literal>) 2436 <literal>host</literal> (<literal>string</literal>)
2278 </tag-name> 2437 </tag-name>
2279 <tag-desc> 2438 <tag-desc>
2280 Hostname of the resolved server. The hostname is assigned automatically and cannot be changed. 2439 Hostname of the resolved server. The hostname is assigned automatically and cannot be changed.
2281 </tag-desc>
2282 <tag-name>
2283 <literal>drain</literal> (<literal>boolean</literal>)
2284 </tag-name>
2285 <tag-desc>
2286 Puts the HTTP upstream server into the “draining” mode. In this mode, only requests <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#sticky">bound</link> to the server will be proxied to it. The parameter cannot be initially set, it can only be changed with the <literal>PATCH</literal> method.
2287 </tag-desc> 2440 </tag-desc>
2288 </list> 2441 </list>
2289 <para>Example:</para> 2442 <para>Example:</para>
2290 <example> 2443 <example>
2291 { 2444 {
2300 "backup" : true, 2453 "backup" : true,
2301 "down" : true 2454 "down" : true
2302 }</example> 2455 }</example>
2303 </listitem> 2456 </listitem>
2304 <listitem id="def_nginx_http_keyval_zone"> 2457 <listitem id="def_nginx_http_keyval_zone">
2305 <para>Keyval Shared Memory Zone:</para> 2458 <para>HTTP Keyval Shared Memory Zone:</para>
2306 Contents of a keyval shared memory zone.<para>Example:</para> 2459 Contents of an HTTP keyval shared memory zone.<para>Example:</para>
2307 <example> 2460 <example>
2308 { 2461 {
2309 "key1" : "value1", 2462 "key1" : "value1",
2310 "key2" : "value2", 2463 "key2" : "value2",
2311 "key3" : "value3" 2464 "key3" : "value3"
2713 "slow_start" : 0, 2866 "slow_start" : 0,
2714 "backup" : false, 2867 "backup" : false,
2715 "down" : false 2868 "down" : false
2716 }</example> 2869 }</example>
2717 </listitem> 2870 </listitem>
2871 <listitem id="def_nginx_stream_keyval_zone">
2872 <para>Stream Keyval Shared Memory Zone:</para>
2873 Contents of a stream keyval shared memory zone.<para>Example:</para>
2874 <example>
2875 {
2876 "key1" : "value1",
2877 "key2" : "value2",
2878 "key3" : "value3"
2879 }</example>
2880 </listitem>
2718 <listitem id="def_nginx_error"> 2881 <listitem id="def_nginx_error">
2719 <para>Error:</para> 2882 <para>Error:</para>
2720 nginx error object.<list type="tag"> 2883 nginx error object.<list type="tag">
2721 <tag-name> 2884 <tag-name>
2722 <literal>path</literal> (<literal>string</literal>) 2885 <literal>path</literal> (<literal>string</literal>)