Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_api_module.xml @ 2992:6e094f915896

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 Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 15 Aug 2023 12:36:26 +0100
parents a85e4d126bc7
children
comparison
equal deleted inserted replaced
2991:1f672755959a 2992:6e094f915896
108 </example> 108 </example>
109 All API requests include 109 All API requests include
110 a supported API <link id="api_version">version</link> in the URI. 110 a supported API <link id="api_version">version</link> in the URI.
111 Examples of API requests with this configuration: 111 Examples of API requests with this configuration:
112 <example> 112 <example>
113 http://127.0.0.1/api/8/ 113 http://127.0.0.1/api/9/
114 http://127.0.0.1/api/8/nginx 114 http://127.0.0.1/api/9/nginx
115 http://127.0.0.1/api/8/connections 115 http://127.0.0.1/api/9/connections
116 http://127.0.0.1/api/8/http/requests 116 http://127.0.0.1/api/9/workers
117 http://127.0.0.1/api/8/http/server_zones/server_backend 117 http://127.0.0.1/api/9/http/requests
118 http://127.0.0.1/api/8/http/caches/cache_backend 118 http://127.0.0.1/api/9/http/server_zones/server_backend
119 http://127.0.0.1/api/8/http/upstreams/backend 119 http://127.0.0.1/api/9/http/caches/cache_backend
120 http://127.0.0.1/api/8/http/upstreams/backend/servers/ 120 http://127.0.0.1/api/9/http/upstreams/backend
121 http://127.0.0.1/api/8/http/upstreams/backend/servers/1 121 http://127.0.0.1/api/9/http/upstreams/backend/servers/
122 http://127.0.0.1/api/8/http/keyvals/one?key=arg1 122 http://127.0.0.1/api/9/http/upstreams/backend/servers/1
123 http://127.0.0.1/api/8/stream/ 123 http://127.0.0.1/api/9/http/keyvals/one?key=arg1
124 http://127.0.0.1/api/8/stream/server_zones/server_backend 124 http://127.0.0.1/api/9/stream/
125 http://127.0.0.1/api/8/stream/upstreams/ 125 http://127.0.0.1/api/9/stream/server_zones/server_backend
126 http://127.0.0.1/api/8/stream/upstreams/backend 126 http://127.0.0.1/api/9/stream/upstreams/
127 http://127.0.0.1/api/8/stream/upstreams/backend/servers/1 127 http://127.0.0.1/api/9/stream/upstreams/backend
128 http://127.0.0.1/api/9/stream/upstreams/backend/servers/1
128 </example> 129 </example>
129 </para> 130 </para>
130 131
131 </section> 132 </section>
132 133
153 154
154 <para id="api_version"> 155 <para id="api_version">
155 All API requests should contain a supported API version in the URI. 156 All API requests should contain a supported API version in the URI.
156 If the request URI equals the location prefix, 157 If the request URI equals the location prefix,
157 the list of supported API versions is returned. 158 the list of supported API versions is returned.
158 The current API version is “<literal>8</literal>”. 159 The current API version is “<literal>9</literal>”.
159 </para> 160 </para>
160 161
161 <para> 162 <para>
162 The optional “<literal>fields</literal>” argument in the request line 163 The optional “<literal>fields</literal>” argument in the request line
163 specifies which fields of the requested objects will be output: 164 specifies which fields of the requested objects will be output:
164 <example> 165 <example>
165 http://127.0.0.1/api/8/nginx?fields=version,build 166 http://127.0.0.1/api/9/nginx?fields=version,build
166 </example> 167 </example>
167 </para> 168 </para>
168 169
169 </directive> 170 </directive>
170 171
204 205
205 <section id="compatibility" name="Compatibility"> 206 <section id="compatibility" name="Compatibility">
206 207
207 <para> 208 <para>
208 <list type="bullet"> 209 <list type="bullet">
210
211 <listitem>
212 The <link id="workers_">/workers/</link> data
213 were added in <link id="api_version">version</link> 9.
214 </listitem>
209 215
210 <listitem> 216 <listitem>
211 Detailed failure counters were added to SSL statistics 217 Detailed failure counters were added to SSL statistics
212 in <link id="api_version">version</link> 8 (1.23.2). 218 in <link id="api_version">version</link> 8 (1.23.2).
213 </listitem> 219 </listitem>
2002 Possible responses: 2008 Possible responses:
2003 </para> 2009 </para>
2004 <list type="bullet"> 2010 <list type="bullet">
2005 <listitem>204 - Success</listitem> 2011 <listitem>204 - Success</listitem>
2006 <listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem> 2012 <listitem>404 - Unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
2013 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
2014 </list>
2015 </listitem>
2016 </list>
2017 </tag-desc>
2018 <tag-name id="workers_" name="/workers/">
2019 <literal>/workers/</literal>
2020 </tag-name>
2021 <tag-desc>
2022 <para>Supported methods:</para>
2023 <list type="bullet" compact="yes">
2024 <listitem id="getWorkers">
2025 <literal>GET</literal> - Return statistics for all worker processes
2026 <para>Returns statistics for all worker processes such as accepted, dropped, active, idle connections, total and current requests.</para>
2027 <para>
2028 Request parameters:
2029 <list type="tag">
2030 <tag-name><literal>fields</literal>
2031 (<literal>string</literal>, optional)</tag-name>
2032 <tag-desc>
2033 Limits which fields of worker process statistics will be output.</tag-desc>
2034 </list>
2035 </para>
2036 <para>
2037 Possible responses:
2038 </para>
2039 <list type="bullet">
2040 <listitem>200 - Success, returns a collection of "<link id="def_nginx_worker">Worker process</link>" objects for all workers</listitem>
2041 <listitem>404 - Worker not found (<literal>WorkerNotFound</literal>),
2042 unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
2043 </list>
2044 </listitem>
2045 <listitem id="deleteWorkersStat">
2046 <literal>DELETE</literal> - Reset statistics for all worker processes.
2047 <para>Resets statistics for all worker processes such as
2048 accepted, dropped, active, idle connections, total and current requests.</para>
2049 <para>
2050 Possible responses:
2051 </para>
2052 <list type="bullet">
2053 <listitem>204 - Success</listitem>
2054 <listitem>404 - Worker not found (<literal>WorkerNotFound</literal>),
2055 unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
2056 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
2057 </list>
2058 </listitem>
2059 </list>
2060 </tag-desc>
2061 <tag-name id="workers_worker_id" name="/workers/{workerId}">
2062 <literal>/workers/{workerId}</literal>
2063 </tag-name>
2064 <tag-desc>
2065 Parameters common for all methods:
2066 <list type="tag">
2067 <tag-name><literal>workerId</literal>
2068 (<literal>string</literal>, required)</tag-name>
2069 <tag-desc>
2070 The ID of the worker process.</tag-desc>
2071 </list>
2072 <para>Supported methods:</para>
2073 <list type="bullet" compact="yes">
2074 <listitem id="getWorker">
2075 <literal>GET</literal> - Return status of a worker process
2076 <para>Returns status of a particular worker process.</para>
2077 <para>
2078 Request parameters:
2079 <list type="tag">
2080 <tag-name><literal>fields</literal>
2081 (<literal>string</literal>, optional)</tag-name>
2082 <tag-desc>
2083 Limits which fields of worker process statistics will be output.</tag-desc>
2084 </list>
2085 </para>
2086 <para>
2087 Possible responses:
2088 </para>
2089 <list type="bullet">
2090 <listitem>200 - Success, returns <link id="def_nginx_worker">Worker process</link></listitem>
2091 <listitem>404 - Worker not found (<literal>WorkerNotFound</literal>),
2092 unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
2093 </list>
2094 </listitem>
2095 <listitem id="deleteWorkerStat">
2096 <literal>DELETE</literal> - Reset statistics for a worker process.
2097 <para>Resets statistics of accepted, dropped, active, idle connections,
2098 as well as total and current requests.</para>
2099 <para>
2100 Possible responses:
2101 </para>
2102 <list type="bullet">
2103 <listitem>204 - Success</listitem>
2104 <listitem>404 - Worker not found (<literal>WorkerNotFound</literal>),
2105 unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
2007 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> 2106 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
2008 </list> 2107 </list>
2009 </listitem> 2108 </listitem>
2010 </list> 2109 </list>
2011 </tag-desc> 2110 </tag-desc>
4344 "unknown" : 478 4443 "unknown" : 478
4345 } 4444 }
4346 } 4445 }
4347 }</example> 4446 }</example>
4348 </listitem> 4447 </listitem>
4448 <listitem id="def_nginx_worker">
4449 <para>Worker process:</para>
4450 Statistics per each worker process.<list type="tag">
4451 <tag-name>
4452 <literal>id</literal> (<literal>integer</literal>)
4453 </tag-name>
4454 <tag-desc>
4455 The ID of the worker process.
4456 </tag-desc>
4457 <tag-name>
4458 <literal>pid</literal> (<literal>integer</literal>)
4459 </tag-name>
4460 <tag-desc>
4461 The PID identifier of the worker process used by the operating system.
4462 </tag-desc>
4463 <tag-name>
4464 <literal>connections</literal></tag-name>
4465 <tag-desc>
4466 The number of accepted, dropped, active, and idle connections
4467 per worker process.<list type="tag">
4468 <tag-name>
4469 <literal>accepted</literal> (<literal>integer</literal>)
4470 </tag-name>
4471 <tag-desc>
4472 The total number of client connections
4473 accepted by the worker process.
4474 </tag-desc>
4475 <tag-name>
4476 <literal>dropped</literal> (<literal>integer</literal>)
4477 </tag-name>
4478 <tag-desc>
4479 The total number of client connections
4480 dropped by the worker process.
4481 </tag-desc>
4482 <tag-name>
4483 <literal>active</literal> (<literal>integer</literal>)
4484 </tag-name>
4485 <tag-desc>
4486 The current number of active client connections
4487 that are currently being handled by the worker process.
4488 </tag-desc>
4489 <tag-name>
4490 <literal>idle</literal> (<literal>integer</literal>)
4491 </tag-name>
4492 <tag-desc>
4493 The number of idle client connections
4494 that are currently being handled by the worker process.
4495 </tag-desc>
4496 </list>
4497 </tag-desc>
4498 <tag-name>
4499 <literal>http</literal></tag-name>
4500 <tag-desc>
4501 <list type="tag">
4502 <tag-name>
4503 <literal>requests</literal></tag-name>
4504 <tag-desc>
4505 The total number of client requests handled by the worker process.<list type="tag">
4506 <tag-name>
4507 <literal>total</literal> (<literal>integer</literal>)
4508 </tag-name>
4509 <tag-desc>
4510 The total number of client requests received by the worker process.
4511 </tag-desc>
4512 <tag-name>
4513 <literal>current</literal> (<literal>integer</literal>)
4514 </tag-name>
4515 <tag-desc>
4516 The current number of client requests that are currently being processed by the worker process.
4517 </tag-desc>
4518 </list>
4519 </tag-desc>
4520 </list>
4521 </tag-desc>
4522 </list>
4523 <para>Example:</para>
4524 <example>
4525 {
4526 "id" : 0,
4527 "pid" : 32212,
4528 "connections" : {
4529 "accepted" : 1,
4530 "dropped" : 0,
4531 "active" : 1,
4532 "idle" : 0
4533 },
4534 "http" : {
4535 "requests" : {
4536 "total" : 15,
4537 "current" : 1
4538 }
4539 }
4540 }</example>
4541 </listitem>
4349 <listitem id="def_nginx_error"> 4542 <listitem id="def_nginx_error">
4350 <para>Error:</para> 4543 <para>Error:</para>
4351 nginx error object.<list type="tag"> 4544 nginx error object.<list type="tag">
4352 <tag-name> 4545 <tag-name>
4353 <literal>error</literal></tag-name> 4546 <literal>error</literal></tag-name>