Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_api_module.xml @ 2359:d5e576eb7677
Updated docs for the upcoming NGINX Plus release.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Mon, 08 Apr 2019 11:45:08 +0300 |
parents | a89093ff86a3 |
children | dd3ac7eefeed |
comparison
equal
deleted
inserted
replaced
2358:ee4eccd811cd | 2359:d5e576eb7677 |
---|---|
99 </example> | 99 </example> |
100 All API requests include | 100 All API requests include |
101 a supported API <link id="api_version">version</link> in the URI. | 101 a supported API <link id="api_version">version</link> in the URI. |
102 Examples of API requests with this configuration: | 102 Examples of API requests with this configuration: |
103 <example> | 103 <example> |
104 http://127.0.0.1/api/3/ | 104 http://127.0.0.1/api/4/ |
105 http://127.0.0.1/api/3/nginx | 105 http://127.0.0.1/api/4/nginx |
106 http://127.0.0.1/api/3/connections | 106 http://127.0.0.1/api/4/connections |
107 http://127.0.0.1/api/3/http/requests | 107 http://127.0.0.1/api/4/http/requests |
108 http://127.0.0.1/api/3/http/server_zones/server_backend | 108 http://127.0.0.1/api/4/http/server_zones/server_backend |
109 http://127.0.0.1/api/3/http/caches/cache_backend | 109 http://127.0.0.1/api/4/http/caches/cache_backend |
110 http://127.0.0.1/api/3/http/upstreams/backend | 110 http://127.0.0.1/api/4/http/upstreams/backend |
111 http://127.0.0.1/api/3/http/upstreams/backend/servers/ | 111 http://127.0.0.1/api/4/http/upstreams/backend/servers/ |
112 http://127.0.0.1/api/3/http/upstreams/backend/servers/1 | 112 http://127.0.0.1/api/4/http/upstreams/backend/servers/1 |
113 http://127.0.0.1/api/3/http/keyvals/one?key=arg1 | 113 http://127.0.0.1/api/4/http/keyvals/one?key=arg1 |
114 http://127.0.0.1/api/3/stream/ | 114 http://127.0.0.1/api/4/stream/ |
115 http://127.0.0.1/api/3/stream/server_zones/server_backend | 115 http://127.0.0.1/api/4/stream/server_zones/server_backend |
116 http://127.0.0.1/api/3/stream/upstreams/ | 116 http://127.0.0.1/api/4/stream/upstreams/ |
117 http://127.0.0.1/api/3/stream/upstreams/backend | 117 http://127.0.0.1/api/4/stream/upstreams/backend |
118 http://127.0.0.1/api/3/stream/upstreams/backend/servers/1 | 118 http://127.0.0.1/api/4/stream/upstreams/backend/servers/1 |
119 </example> | 119 </example> |
120 </para> | 120 </para> |
121 | 121 |
122 </section> | 122 </section> |
123 | 123 |
144 | 144 |
145 <para id="api_version"> | 145 <para id="api_version"> |
146 All API requests should contain a supported API version in the URI. | 146 All API requests should contain a supported API version in the URI. |
147 If the request URI equals the location prefix, | 147 If the request URI equals the location prefix, |
148 the list of supported API versions is returned. | 148 the list of supported API versions is returned. |
149 The current API version is “<literal>3</literal>”. | 149 The current API version is “<literal>4</literal>”. |
150 </para> | 150 </para> |
151 | 151 |
152 <para> | 152 <para> |
153 The optional “<literal>fields</literal>” argument in the request line | 153 The optional “<literal>fields</literal>” argument in the request line |
154 specifies which fields of the requested objects will be output: | 154 specifies which fields of the requested objects will be output: |
155 <example> | 155 <example> |
156 http://127.0.0.1/api/3/nginx?fields=version,build | 156 http://127.0.0.1/api/4/nginx?fields=version,build |
157 </example> | 157 </example> |
158 </para> | 158 </para> |
159 | 159 |
160 </directive> | 160 </directive> |
161 | 161 |
181 | 181 |
182 <section id="compatibility" name="Compatibility"> | 182 <section id="compatibility" name="Compatibility"> |
183 | 183 |
184 <para> | 184 <para> |
185 <list type="bullet"> | 185 <list type="bullet"> |
186 | |
187 <listitem> | |
188 The <literal>path</literal> and <literal>method</literal> fields of | |
189 <link id="def_nginx_error">nginx error object</link> | |
190 were removed in <link id="api_version">version</link> 4. | |
191 These fields continue to exist in earlier api versions, | |
192 but show an empty value. | |
193 </listitem> | |
186 | 194 |
187 <listitem> | 195 <listitem> |
188 The <link id="stream_zone_sync_">/stream/zone_sync/</link> data | 196 The <link id="stream_zone_sync_">/stream/zone_sync/</link> data |
189 were added in <link id="api_version">version</link> 3. | 197 were added in <link id="api_version">version</link> 3. |
190 </listitem> | 198 </listitem> |
950 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 958 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
951 </list> | 959 </list> |
952 </listitem> | 960 </listitem> |
953 <listitem id="patchHttpKeyvalZoneKeyValue"> | 961 <listitem id="patchHttpKeyvalZoneKeyValue"> |
954 <literal>PATCH</literal> - Modify a key-value or delete a key | 962 <literal>PATCH</literal> - Modify a key-value or delete a key |
955 <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> | 963 <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> |
956 <para> | 964 <para> |
957 Request parameters: | 965 Request parameters: |
958 <list type="tag"> | 966 <list type="tag"> |
959 <tag-name><literal>httpKeyvalZoneKeyValue</literal> | 967 <tag-name><literal>httpKeyvalZoneKeyValue</literal> |
960 (<link id="def_nginx_http_keyval_zone">HTTP Keyval Shared Memory Zone</link>, required)</tag-name> | 968 (<link id="def_nginx_http_keyval_zone">HTTP Keyval Shared Memory Zone</link>, required)</tag-name> |
976 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 984 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
977 </list> | 985 </list> |
978 </listitem> | 986 </listitem> |
979 <listitem id="deleteHttpKeyvalZoneData"> | 987 <listitem id="deleteHttpKeyvalZoneData"> |
980 <literal>DELETE</literal> - Empty the HTTP keyval zone | 988 <literal>DELETE</literal> - Empty the HTTP keyval zone |
981 <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> | 989 <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>. 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, empties the keyval zone only on a target cluster node.</para> |
982 <para> | 990 <para> |
983 Possible responses: | 991 Possible responses: |
984 </para> | 992 </para> |
985 <list type="bullet"> | 993 <list type="bullet"> |
986 <listitem>204 - Success</listitem> | 994 <listitem>204 - Success</listitem> |
1029 <para> | 1037 <para> |
1030 Possible responses: | 1038 Possible responses: |
1031 </para> | 1039 </para> |
1032 <list type="bullet"> | 1040 <list type="bullet"> |
1033 <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> | 1041 <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> |
1034 <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> | |
1035 </list> | 1042 </list> |
1036 </listitem> | 1043 </listitem> |
1037 </list> | 1044 </list> |
1038 </tag-desc> | 1045 </tag-desc> |
1039 <tag-name id="stream_server_zones_stream_server_zone_name" name="/stream/server_zones/{streamServerZoneName}"> | 1046 <tag-name id="stream_server_zones_stream_server_zone_name" name="/stream/server_zones/{streamServerZoneName}"> |
1064 <para> | 1071 <para> |
1065 Possible responses: | 1072 Possible responses: |
1066 </para> | 1073 </para> |
1067 <list type="bullet"> | 1074 <list type="bullet"> |
1068 <listitem>200 - Success, returns <link id="def_nginx_stream_server_zone">Stream Server Zone</link></listitem> | 1075 <listitem>200 - Success, returns <link id="def_nginx_stream_server_zone">Stream Server Zone</link></listitem> |
1069 <listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>), | 1076 <listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1070 <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> | |
1071 </list> | 1077 </list> |
1072 </listitem> | 1078 </listitem> |
1073 <listitem id="deleteStreamServerZoneStat"> | 1079 <listitem id="deleteStreamServerZoneStat"> |
1074 <literal>DELETE</literal> - Reset statistics for a stream server zone | 1080 <literal>DELETE</literal> - Reset statistics for a stream server zone |
1075 <para>Resets statistics of accepted and discarded connections, sessions, received and sent bytes in a particular stream server zone.</para> | 1081 <para>Resets statistics of accepted and discarded connections, sessions, received and sent bytes in a particular stream server zone.</para> |
1076 <para> | 1082 <para> |
1077 Possible responses: | 1083 Possible responses: |
1078 </para> | 1084 </para> |
1079 <list type="bullet"> | 1085 <list type="bullet"> |
1080 <listitem>204 - Success</listitem> | 1086 <listitem>204 - Success</listitem> |
1081 <listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>), | 1087 <listitem>404 - Server zone not found (<literal>ServerZoneNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1082 <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> | |
1083 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1088 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1084 </list> | 1089 </list> |
1085 </listitem> | 1090 </listitem> |
1086 </list> | 1091 </list> |
1087 </tag-desc> | 1092 </tag-desc> |
1106 <para> | 1111 <para> |
1107 Possible responses: | 1112 Possible responses: |
1108 </para> | 1113 </para> |
1109 <list type="bullet"> | 1114 <list type="bullet"> |
1110 <listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_upstream">Stream Upstream</link>" objects for all stream upstreams </listitem> | 1115 <listitem>200 - Success, returns a collection of "<link id="def_nginx_stream_upstream">Stream Upstream</link>" objects for all stream upstreams </listitem> |
1111 <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> | |
1112 </list> | 1116 </list> |
1113 </listitem> | 1117 </listitem> |
1114 </list> | 1118 </list> |
1115 </tag-desc> | 1119 </tag-desc> |
1116 <tag-name id="stream_upstreams_stream_upstream_name_" name="/stream/upstreams/{streamUpstreamName}/"> | 1120 <tag-name id="stream_upstreams_stream_upstream_name_" name="/stream/upstreams/{streamUpstreamName}/"> |
1142 Possible responses: | 1146 Possible responses: |
1143 </para> | 1147 </para> |
1144 <list type="bullet"> | 1148 <list type="bullet"> |
1145 <listitem>200 - Success, returns <link id="def_nginx_stream_upstream">Stream Upstream</link></listitem> | 1149 <listitem>200 - Success, returns <link id="def_nginx_stream_upstream">Stream Upstream</link></listitem> |
1146 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1150 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1147 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | 1151 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1148 <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> | |
1149 </list> | 1152 </list> |
1150 </listitem> | 1153 </listitem> |
1151 <listitem id="deleteStreamUpstreamStat"> | 1154 <listitem id="deleteStreamUpstreamStat"> |
1152 <literal>DELETE</literal> - Reset statistics of a stream upstream server group | 1155 <literal>DELETE</literal> - Reset statistics of a stream upstream server group |
1153 <para>Resets the statistics for each upstream server in an upstream server group.</para> | 1156 <para>Resets the statistics for each upstream server in an upstream server group.</para> |
1155 Possible responses: | 1158 Possible responses: |
1156 </para> | 1159 </para> |
1157 <list type="bullet"> | 1160 <list type="bullet"> |
1158 <listitem>204 - Success</listitem> | 1161 <listitem>204 - Success</listitem> |
1159 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1162 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1160 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | 1163 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1161 <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> | |
1162 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1164 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1163 </list> | 1165 </list> |
1164 </listitem> | 1166 </listitem> |
1165 </list> | 1167 </list> |
1166 </tag-desc> | 1168 </tag-desc> |
1184 Possible responses: | 1186 Possible responses: |
1185 </para> | 1187 </para> |
1186 <list type="bullet"> | 1188 <list type="bullet"> |
1187 <listitem>200 - Success, returns an array of <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Servers</link></listitem> | 1189 <listitem>200 - Success, returns an array of <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Servers</link></listitem> |
1188 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1190 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1189 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | 1191 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1190 <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> | |
1191 </list> | 1192 </list> |
1192 </listitem> | 1193 </listitem> |
1193 <listitem id="postStreamUpstreamServer"> | 1194 <listitem id="postStreamUpstreamServer"> |
1194 <literal>POST</literal> - Add a server to a stream upstream server group | 1195 <literal>POST</literal> - Add a server to a stream upstream server group |
1195 <para>Adds a new server to a stream upstream server group. Server parameters are specified in the JSON format.</para> | 1196 <para>Adds a new server to a stream upstream server group. Server parameters are specified in the JSON format.</para> |
1223 invalid “<literal>slow_start</literal>” (<literal>UpstreamBadSlowStart</literal>), | 1224 invalid “<literal>slow_start</literal>” (<literal>UpstreamBadSlowStart</literal>), |
1224 “<literal>service</literal>” is empty (<literal>UpstreamBadService</literal>), | 1225 “<literal>service</literal>” is empty (<literal>UpstreamBadService</literal>), |
1225 no resolver defined to resolve (<literal>UpstreamConfNoResolver</literal>), | 1226 no resolver defined to resolve (<literal>UpstreamConfNoResolver</literal>), |
1226 upstream “<value>name</value>” has no backup (<literal>UpstreamNoBackup</literal>), | 1227 upstream “<value>name</value>” has no backup (<literal>UpstreamNoBackup</literal>), |
1227 upstream “<value>name</value>” memory exhausted (<literal>UpstreamOutOfMemory</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1228 upstream “<value>name</value>” memory exhausted (<literal>UpstreamOutOfMemory</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1228 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | 1229 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1229 <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> | |
1230 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1230 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1231 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1231 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1232 </list> | 1232 </list> |
1233 </listitem> | 1233 </listitem> |
1234 </list> | 1234 </list> |
1259 <list type="bullet"> | 1259 <list type="bullet"> |
1260 <listitem>200 - Success, returns <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link></listitem> | 1260 <listitem>200 - Success, returns <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Server</link></listitem> |
1261 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), | 1261 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), |
1262 invalid server ID (<literal>UpstreamBadServerId</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1262 invalid server ID (<literal>UpstreamBadServerId</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1263 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | 1263 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), |
1264 server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), | 1264 server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1265 <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> | |
1266 </list> | 1265 </list> |
1267 </listitem> | 1266 </listitem> |
1268 <listitem id="patchStreamUpstreamServer"> | 1267 <listitem id="patchStreamUpstreamServer"> |
1269 <literal>PATCH</literal> - Modify a server in a stream upstream server group | 1268 <literal>PATCH</literal> - Modify a server in a stream upstream server group |
1270 <para>Modifies settings of a particular server in a stream upstream server group. Server parameters are specified in the JSON format.</para> | 1269 <para>Modifies settings of a particular server in a stream upstream server group. Server parameters are specified in the JSON format.</para> |
1298 “<literal>service</literal>” is empty (<literal>UpstreamBadService</literal>), | 1297 “<literal>service</literal>” is empty (<literal>UpstreamBadService</literal>), |
1299 server “<value>ID</value>” address is immutable (<literal>UpstreamServerImmutable</literal>), | 1298 server “<value>ID</value>” address is immutable (<literal>UpstreamServerImmutable</literal>), |
1300 server “<value>ID</value>” weight is immutable (<literal>UpstreamServerWeightImmutable</literal>), | 1299 server “<value>ID</value>” weight is immutable (<literal>UpstreamServerWeightImmutable</literal>), |
1301 upstream “<literal>name</literal>” memory exhausted (<literal>UpstreamOutOfMemory</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1300 upstream “<literal>name</literal>” memory exhausted (<literal>UpstreamOutOfMemory</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1302 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | 1301 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), |
1303 server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), | 1302 server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1304 <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> | |
1305 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1303 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1306 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1304 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1307 </list> | 1305 </list> |
1308 </listitem> | 1306 </listitem> |
1309 <listitem id="deleteStreamUpstreamServer"> | 1307 <listitem id="deleteStreamUpstreamServer"> |
1316 <listitem>200 - Success, returns an array of <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Servers</link></listitem> | 1314 <listitem>200 - Success, returns an array of <link id="def_nginx_stream_upstream_conf_server">Stream Upstream Servers</link></listitem> |
1317 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), | 1315 <listitem>400 - Upstream is static (<literal>UpstreamStatic</literal>), |
1318 invalid server ID (<literal>UpstreamBadServerId</literal>), | 1316 invalid server ID (<literal>UpstreamBadServerId</literal>), |
1319 server “<value>id</value>” not removable (<literal>UpstreamServerImmutable</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1317 server “<value>id</value>” not removable (<literal>UpstreamServerImmutable</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1320 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), | 1318 <listitem>404 - Upstream not found (<literal>UpstreamNotFound</literal>), |
1321 server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), | 1319 server with ID “<value>id</value>” does not exist (<literal>UpstreamServerNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1322 <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> | |
1323 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1320 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1324 </list> | 1321 </list> |
1325 </listitem> | 1322 </listitem> |
1326 </list> | 1323 </list> |
1327 </tag-desc> | 1324 </tag-desc> |
1346 <para> | 1343 <para> |
1347 Possible responses: | 1344 Possible responses: |
1348 </para> | 1345 </para> |
1349 <list type="bullet"> | 1346 <list type="bullet"> |
1350 <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> | 1347 <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> |
1351 <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> | |
1352 </list> | 1348 </list> |
1353 </listitem> | 1349 </listitem> |
1354 </list> | 1350 </list> |
1355 </tag-desc> | 1351 </tag-desc> |
1356 <tag-name id="stream_keyvals_stream_keyval_zone_name" name="/stream/keyvals/{streamKeyvalZoneName}"> | 1352 <tag-name id="stream_keyvals_stream_keyval_zone_name" name="/stream/keyvals/{streamKeyvalZoneName}"> |
1382 Possible responses: | 1378 Possible responses: |
1383 </para> | 1379 </para> |
1384 <list type="bullet"> | 1380 <list type="bullet"> |
1385 <listitem>200 - Success, returns <link id="def_nginx_stream_keyval_zone">Stream Keyval Shared Memory Zone</link></listitem> | 1381 <listitem>200 - Success, returns <link id="def_nginx_stream_keyval_zone">Stream Keyval Shared Memory Zone</link></listitem> |
1386 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), | 1382 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), |
1387 keyval key not found (<literal>KeyvalKeyNotFound</literal>), | 1383 keyval key not found (<literal>KeyvalKeyNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1388 <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> | |
1389 </list> | 1384 </list> |
1390 </listitem> | 1385 </listitem> |
1391 <listitem id="postStreamKeyvalZoneData"> | 1386 <listitem id="postStreamKeyvalZoneData"> |
1392 <literal>POST</literal> - Add a key-value pair to the stream keyval zone | 1387 <literal>POST</literal> - Add a key-value pair to the stream keyval zone |
1393 <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> | 1388 <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> |
1406 <list type="bullet"> | 1401 <list type="bullet"> |
1407 <listitem>201 - Created</listitem> | 1402 <listitem>201 - Created</listitem> |
1408 <listitem>400 - Key required (<literal>KeyvalFormatError</literal>), | 1403 <listitem>400 - Key required (<literal>KeyvalFormatError</literal>), |
1409 only one key can be added (<literal>KeyvalFormatError</literal>), | 1404 only one key can be added (<literal>KeyvalFormatError</literal>), |
1410 nested object or list (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1405 nested object or list (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1411 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), | 1406 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1412 <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> | |
1413 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1407 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1414 <listitem>409 - Key already exists (<literal>KeyvalKeyExists</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1408 <listitem>409 - Key already exists (<literal>KeyvalKeyExists</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1415 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1409 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1416 </list> | 1410 </list> |
1417 </listitem> | 1411 </listitem> |
1418 <listitem id="patchStreamKeyvalZoneKeyValue"> | 1412 <listitem id="patchStreamKeyvalZoneKeyValue"> |
1419 <literal>PATCH</literal> - Modify a key-value or delete a key | 1413 <literal>PATCH</literal> - Modify a key-value or delete a key |
1420 <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> | 1414 <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> |
1421 <para> | 1415 <para> |
1422 Request parameters: | 1416 Request parameters: |
1423 <list type="tag"> | 1417 <list type="tag"> |
1424 <tag-name><literal>streamKeyvalZoneKeyValue</literal> | 1418 <tag-name><literal>streamKeyvalZoneKeyValue</literal> |
1425 (<link id="def_nginx_stream_keyval_zone">Stream Keyval Shared Memory Zone</link>, required)</tag-name> | 1419 (<link id="def_nginx_stream_keyval_zone">Stream Keyval Shared Memory Zone</link>, required)</tag-name> |
1434 <listitem>204 - Success</listitem> | 1428 <listitem>204 - Success</listitem> |
1435 <listitem>400 - Key required (<literal>KeyvalFormatError</literal>), | 1429 <listitem>400 - Key required (<literal>KeyvalFormatError</literal>), |
1436 only one key can be updated (<literal>KeyvalFormatError</literal>), | 1430 only one key can be updated (<literal>KeyvalFormatError</literal>), |
1437 nested object or list (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1431 nested object or list (<literal>KeyvalFormatError</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1438 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), | 1432 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), |
1439 keyval key not found (<literal>KeyvalKeyNotFound</literal>), | 1433 keyval key not found (<literal>KeyvalKeyNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1440 <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> | |
1441 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1434 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1442 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1435 <listitem>415 - JSON error (<literal>JsonError</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1443 </list> | 1436 </list> |
1444 </listitem> | 1437 </listitem> |
1445 <listitem id="deleteStreamKeyvalZoneData"> | 1438 <listitem id="deleteStreamKeyvalZoneData"> |
1446 <literal>DELETE</literal> - Empty the stream keyval zone | 1439 <literal>DELETE</literal> - Empty the stream keyval zone |
1447 <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> | 1440 <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>. 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, empties the keyval zone only on a target cluster node.</para> |
1448 <para> | 1441 <para> |
1449 Possible responses: | 1442 Possible responses: |
1450 </para> | 1443 </para> |
1451 <list type="bullet"> | 1444 <list type="bullet"> |
1452 <listitem>204 - Success</listitem> | 1445 <listitem>204 - Success</listitem> |
1453 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), | 1446 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1454 <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> | |
1455 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> | 1447 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> |
1456 </list> | 1448 </list> |
1457 </listitem> | 1449 </listitem> |
1458 </list> | 1450 </list> |
1459 </tag-desc> | 1451 </tag-desc> |
1469 <para> | 1461 <para> |
1470 Possible responses: | 1462 Possible responses: |
1471 </para> | 1463 </para> |
1472 <list type="bullet"> | 1464 <list type="bullet"> |
1473 <listitem>200 - Success, returns <link id="def_nginx_stream_zone_sync">Stream Zone Sync Node</link></listitem> | 1465 <listitem>200 - Success, returns <link id="def_nginx_stream_zone_sync">Stream Zone Sync Node</link></listitem> |
1474 <listitem>404 - Zone sync not configured (<literal>ZoneSyncNotConfigured</literal>), | |
1475 <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> | |
1476 </list> | 1466 </list> |
1477 </listitem> | 1467 </listitem> |
1478 </list> | 1468 </list> |
1479 </tag-desc> | 1469 </tag-desc> |
1480 </list> | 1470 </list> |
3007 </listitem> | 2997 </listitem> |
3008 <listitem id="def_nginx_error"> | 2998 <listitem id="def_nginx_error"> |
3009 <para>Error:</para> | 2999 <para>Error:</para> |
3010 nginx error object.<list type="tag"> | 3000 nginx error object.<list type="tag"> |
3011 <tag-name> | 3001 <tag-name> |
3012 <literal>path</literal> (<literal>string</literal>) | |
3013 </tag-name> | |
3014 <tag-desc> | |
3015 API path. | |
3016 </tag-desc> | |
3017 <tag-name> | |
3018 <literal>method</literal> (<literal>string</literal>) | |
3019 </tag-name> | |
3020 <tag-desc> | |
3021 HTTP method. | |
3022 </tag-desc> | |
3023 <tag-name> | |
3024 <literal>error</literal></tag-name> | 3002 <literal>error</literal></tag-name> |
3025 <tag-desc> | 3003 <tag-desc> |
3026 <list type="tag"> | 3004 <list type="tag"> |
3027 <tag-name> | 3005 <tag-name> |
3028 <literal>status</literal> (<literal>integer</literal>) | 3006 <literal>status</literal> (<literal>integer</literal>) |