Mercurial > hg > nginx-site

annotate xml/en/docs/http/ngx_http_api_module_head.xml @ 2469:98fd810c13e0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated docs for the upcoming NGINX Plus release.
author Ruslan Ermilov <ru@nginx.com>
date Mon, 02 Dec 2019 13:23:05 +0300
parents dd3ac7eefeed
children 407147d8020f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2028
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
1 <?xml version="1.0"?>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
2
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
3 <!--
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
4 Copyright (C) Nginx, Inc.
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
5 -->
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
6
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
8
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
9 <module name="Module ngx_http_api_module"
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
10 link="/en/docs/http/ngx_http_api_module.html"
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
11 lang="en"
2221
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
12 rev="2">
2028
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
13
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
14 <section id="summary">
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
15
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
16 <para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
17 The <literal>ngx_http_api_module</literal> module (1.13.3) provides REST API
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
18 for accessing various status information,
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
19 configuring upstream server groups on-the-fly, and managing
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
20 <link doc="ngx_http_keyval_module.xml">key-value pairs</link>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
21 without the need of reconfiguring nginx.
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
22 </para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
23
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
24 <para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
25 <note>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
26 The module supersedes the
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
27 <link doc="ngx_http_status_module.xml">ngx_http_status_module</link> and
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
28 <link doc="ngx_http_upstream_conf_module.xml">ngx_http_upstream_conf_module</link>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
29 modules.
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
30 </note>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
31 </para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
32
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
33 <para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
34 <note>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
35 This module is available as part of our
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
36 <commercial_version>commercial subscription</commercial_version>.
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
37 </note>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
38 </para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
39
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
40 </section>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
41
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
42
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
43 <section id="example" name="Example Configuration">
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
44
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
45 <para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
46 <example>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
47 http {
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
48 upstream backend {
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
49 zone http_backend 64k;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
50
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
51 server backend1.example.com weight=5;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
52 server backend2.example.com;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
53 }
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
54
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
55 proxy_cache_path /data/nginx/cache_backend keys_zone=cache_backend:10m;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
56
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
57 server {
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
58 server_name backend.example.com;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
59
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
60 location / {
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
61 proxy_pass http://backend;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
62 proxy_cache cache_backend;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
63
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
64 health_check;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
65 }
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
66
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
67 status_zone server_backend;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
68 }
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
69
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
70 keyval_zone zone=one:32k state=one.keyval;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
71 keyval $arg_text $text zone=one;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
72
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
73 server {
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
74 listen 127.0.0.1;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
75
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
76 location /api {
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
77 <emphasis>api</emphasis> write=on;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
78 allow 127.0.0.1;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
79 deny all;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
80 }
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
81 }
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
82 }
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
83
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
84 stream {
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
85 upstream backend {
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
86 zone stream_backend 64k;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
87
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
88 server backend1.example.com:12345 weight=5;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
89 server backend2.example.com:12345;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
90 }
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
91
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
92 server {
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
93 listen 127.0.0.1:12345;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
94 proxy_pass backend;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
95 status_zone server_backend;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
96 health_check;
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
97 }
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
98 }
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
99 </example>
2082
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
100 All API requests include
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
101 a supported API <link id="api_version">version</link> in the URI.
2028
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
102 Examples of API requests with this configuration:
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
103 <example>
2469
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
104 http://127.0.0.1/api/6/
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
105 http://127.0.0.1/api/6/nginx
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
106 http://127.0.0.1/api/6/connections
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
107 http://127.0.0.1/api/6/http/requests
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
108 http://127.0.0.1/api/6/http/server_zones/server_backend
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
109 http://127.0.0.1/api/6/http/caches/cache_backend
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
110 http://127.0.0.1/api/6/http/upstreams/backend
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
111 http://127.0.0.1/api/6/http/upstreams/backend/servers/
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
112 http://127.0.0.1/api/6/http/upstreams/backend/servers/1
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
113 http://127.0.0.1/api/6/http/keyvals/one?key=arg1
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
114 http://127.0.0.1/api/6/stream/
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
115 http://127.0.0.1/api/6/stream/server_zones/server_backend
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
116 http://127.0.0.1/api/6/stream/upstreams/
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
117 http://127.0.0.1/api/6/stream/upstreams/backend
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
118 http://127.0.0.1/api/6/stream/upstreams/backend/servers/1
2028
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
119 </example>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
120 </para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
121
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
122 </section>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
123
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
124
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
125 <section id="directives" name="Directives">
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
126
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
127 <directive name="api">
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
128 <syntax>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
129 [<literal>write</literal>=<literal>on</literal>|<literal>off</literal>]</syntax>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
130 <default/>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
131 <context>location</context>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
132
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
133 <para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
134 Turns on the REST API interface in the surrounding location.
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
135 Access to this location should be
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
136 <link doc="ngx_http_core_module.xml" id="satisfy">limited</link>.
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
137 </para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
138
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
139 <para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
140 The <literal>write</literal> parameter determines whether the API
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
141 is read-only or read-write.
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
142 By default, the API is read-only.
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
143 </para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
144
2082
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
145 <para id="api_version">
2028
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
146 All API requests should contain a supported API version in the URI.
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
147 If the request URI equals the location prefix,
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
148 the list of supported API versions is returned.
2469
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
149 The current API version is “<literal>6</literal>”.
2028
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
150 </para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
151
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
152 <para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
153 The optional “<literal>fields</literal>” argument in the request line
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
154 specifies which fields of the requested objects will be output:
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
155 <example>
2469
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
156 http://127.0.0.1/api/6/nginx?fields=version,build
2028
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
157 </example>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
158 </para>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
159
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
160 </directive>
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
161
2221
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
162
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
163 <directive name="status_zone">
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
164 <syntax><value>zone</value></syntax>
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
165 <default/>
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
166 <context>server</context>
2424
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
167 <context>location</context>
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
168 <context>if in location</context>
2221
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
169 <appeared-in>1.13.12</appeared-in>
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
170
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
171 <para>
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
172 Enables collection of virtual
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
173 <link doc="ngx_http_core_module.xml" id="server">http</link>
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
174 or
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
175 <link doc="../stream/ngx_stream_core_module.xml" id="server">stream</link>
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
176 server status information in the specified <value>zone</value>.
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
177 Several servers may share the same zone.
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
178 </para>
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
179
2424
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
180 <para id="status_zone_location">
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
181 Starting from 1.17.0, status information can be collected
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
182 per <link doc="ngx_http_core_module.xml" id="location"/>.
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
183 The special value <literal>off</literal> disables statistics collection
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
184 in nested location blocks.
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
185 Note that the statistics is collected
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
186 in the context of a location where processing ends.
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
187 It may be different from the original location, if an
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
188 <link doc="ngx_http_core_module.xml" id="internal">internal
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
189 redirect</link> happens during request processing.
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
190 </para>
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
191
2221
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
192 </directive>
45a2b90247ad Added "status_zone" to the API module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2139
diff changeset
193
2028
5c55b7054b58 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
194 </section>
2082
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
195
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
196 <section id="compatibility" name="Compatibility">
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
197
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
198 <para>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
199 <list type="bullet">
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
200
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
201 <listitem>
2469
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
202 The <link id="stream_limit_conns_">/stream/limit_conns/</link> data
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
203 were added in <link id="api_version">version</link> 6.
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
204 </listitem>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
205
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
206 <listitem>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
207 The <link id="http_limit_conns_">/http/limit_conns/</link> data
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
208 were added in <link id="api_version">version</link> 6.
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
209 </listitem>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
210
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
211 <listitem>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
212 The <link id="http_limit_reqs_">/http/limit_reqs/</link> data
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
213 were added in <link id="api_version">version</link> 6.
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
214 </listitem>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
215
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2424
diff changeset
216 <listitem>
2424
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
217 The “<literal>expire</literal>” parameter of a
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
218 <link doc="ngx_http_keyval_module.xml">key-value</link> pair can be
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
219 <link id="postHttpKeyvalZoneData">set</link> or
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
220 <link id="patchHttpKeyvalZoneKeyValue">changed</link>
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
221 since <link id="api_version">version</link> 5.
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
222 </listitem>
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
223
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
224 <listitem>
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
225 The <link id="resolvers_">/resolvers/</link> data
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
226 were added in <link id="api_version">version</link> 5.
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
227 </listitem>
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
228
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
229 <listitem>
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
230 The <link id="http_location_zones_">/http/location_zones/</link> data
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
231 were added in <link id="api_version">version</link> 5.
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
232 </listitem>
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
233
dd3ac7eefeed Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2359
diff changeset
234 <listitem>
2359
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2221
diff changeset
235 The <literal>path</literal> and <literal>method</literal> fields of
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2221
diff changeset
236 <link id="def_nginx_error">nginx error object</link>
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2221
diff changeset
237 were removed in <link id="api_version">version</link> 4.
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2221
diff changeset
238 These fields continue to exist in earlier api versions,
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2221
diff changeset
239 but show an empty value.
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2221
diff changeset
240 </listitem>
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2221
diff changeset
241
d5e576eb7677 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2221
diff changeset
242 <listitem>
2139
f6e578b1b02d Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2082
diff changeset
243 The <link id="stream_zone_sync_">/stream/zone_sync/</link> data
f6e578b1b02d Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2082
diff changeset
244 were added in <link id="api_version">version</link> 3.
f6e578b1b02d Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2082
diff changeset
245 </listitem>
f6e578b1b02d Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2082
diff changeset
246
f6e578b1b02d Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2082
diff changeset
247 <listitem>
2082
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
248 The <link id="def_nginx_http_upstream_conf_server">drain</link> parameter
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
249 was added in <link id="api_version">version</link> 2.
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
250 </listitem>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
251
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
252 <listitem>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
253 The <link id="stream_keyvals_">/stream/keyvals/</link> data
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
254 were added in <link id="api_version">version</link> 2.
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
255 </listitem>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
256
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
257 </list>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
258 </para>
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
259
fee7627f6a5a Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2028
diff changeset
260 </section>