Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_api_module.xml @ 2139:f6e578b1b02d

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, 09 Apr 2018 11:52:48 +0300
parents bb3d2ce5192e
children 45a2b90247ad
comparison
equal deleted inserted replaced
2138:cf86c259c9a0 2139:f6e578b1b02d
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/2/ 104 http://127.0.0.1/api/3/
105 http://127.0.0.1/api/2/nginx 105 http://127.0.0.1/api/3/nginx
106 http://127.0.0.1/api/2/connections 106 http://127.0.0.1/api/3/connections
107 http://127.0.0.1/api/2/http/requests 107 http://127.0.0.1/api/3/http/requests
108 http://127.0.0.1/api/2/http/server_zones/server_backend 108 http://127.0.0.1/api/3/http/server_zones/server_backend
109 http://127.0.0.1/api/2/http/caches/cache_backend 109 http://127.0.0.1/api/3/http/caches/cache_backend
110 http://127.0.0.1/api/2/http/upstreams/backend 110 http://127.0.0.1/api/3/http/upstreams/backend
111 http://127.0.0.1/api/2/http/upstreams/backend/servers/ 111 http://127.0.0.1/api/3/http/upstreams/backend/servers/
112 http://127.0.0.1/api/2/http/upstreams/backend/servers/1 112 http://127.0.0.1/api/3/http/upstreams/backend/servers/1
113 http://127.0.0.1/api/2/http/keyvals/one?key=arg1 113 http://127.0.0.1/api/3/http/keyvals/one?key=arg1
114 http://127.0.0.1/api/2/stream/ 114 http://127.0.0.1/api/3/stream/
115 http://127.0.0.1/api/2/stream/server_zones/server_backend 115 http://127.0.0.1/api/3/stream/server_zones/server_backend
116 http://127.0.0.1/api/2/stream/upstreams/ 116 http://127.0.0.1/api/3/stream/upstreams/
117 http://127.0.0.1/api/2/stream/upstreams/backend 117 http://127.0.0.1/api/3/stream/upstreams/backend
118 http://127.0.0.1/api/2/stream/upstreams/backend/servers/1 118 http://127.0.0.1/api/3/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>2</literal>”. 149 The current API version is “<literal>3</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/2/nginx?fields=version,build 156 http://127.0.0.1/api/3/nginx?fields=version,build
157 </example> 157 </example>
158 </para> 158 </para>
159 159
160 </directive> 160 </directive>
161 161
163 163
164 <section id="compatibility" name="Compatibility"> 164 <section id="compatibility" name="Compatibility">
165 165
166 <para> 166 <para>
167 <list type="bullet"> 167 <list type="bullet">
168
169 <listitem>
170 The <link id="stream_zone_sync_">/stream/zone_sync/</link> data
171 were added in <link id="api_version">version</link> 3.
172 </listitem>
168 173
169 <listitem> 174 <listitem>
170 The <link id="def_nginx_http_upstream_conf_server">drain</link> parameter 175 The <link id="def_nginx_http_upstream_conf_server">drain</link> parameter
171 was added in <link id="api_version">version</link> 2. 176 was added in <link id="api_version">version</link> 2.
172 </listitem> 177 </listitem>
1428 <list type="bullet"> 1433 <list type="bullet">
1429 <listitem>204 - Success</listitem> 1434 <listitem>204 - Success</listitem>
1430 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>), 1435 <listitem>404 - Keyval not found (<literal>KeyvalNotFound</literal>),
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> 1436 <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>
1432 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem> 1437 <listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
1438 </list>
1439 </listitem>
1440 </list>
1441 </tag-desc>
1442 <tag-name id="stream_zone_sync_" name="/stream/zone_sync/">
1443 <literal>/stream/zone_sync/</literal>
1444 </tag-name>
1445 <tag-desc>
1446 <para>Supported methods:</para>
1447 <list type="bullet" compact="yes">
1448 <listitem id="getStreamZoneSync">
1449 <literal>GET</literal> - Return sync status of a node
1450 <para>Returns synchronization status of a cluster node.</para>
1451 <para>
1452 Possible responses:
1453 </para>
1454 <list type="bullet">
1455 <listitem>200 - Success, returns <link id="def_nginx_stream_zone_sync">Stream Zone Sync Node</link></listitem>
1456 <listitem>404 - Zone sync not configured (<literal>ZoneSyncNotConfigured</literal>),
1457 <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>
1433 </list> 1458 </list>
1434 </listitem> 1459 </listitem>
1435 </list> 1460 </list>
1436 </tag-desc> 1461 </tag-desc>
1437 </list> 1462 </list>
2876 "key1" : "value1", 2901 "key1" : "value1",
2877 "key2" : "value2", 2902 "key2" : "value2",
2878 "key3" : "value3" 2903 "key3" : "value3"
2879 }</example> 2904 }</example>
2880 </listitem> 2905 </listitem>
2906 <listitem id="def_nginx_stream_zone_sync">
2907 <para>Stream Zone Sync Node:</para>
2908 <list type="tag">
2909 <tag-name>
2910 <literal>zones</literal></tag-name>
2911 <tag-desc>
2912 <para>Synchronization information per each shared memory zone.</para><para>A collection of "<link id="def_nginx_stream_zone_sync_zone">Sync Zone</link>" objects</para>
2913 </tag-desc>
2914 <tag-name>
2915 <literal>status</literal></tag-name>
2916 <tag-desc>
2917 Synchronization information per node in a cluster.<list type="tag">
2918 <tag-name>
2919 <literal>bytes_in</literal> (<literal>integer</literal>)
2920 </tag-name>
2921 <tag-desc>
2922 The number of bytes received by this node.
2923 </tag-desc>
2924 <tag-name>
2925 <literal>msgs_in</literal> (<literal>integer</literal>)
2926 </tag-name>
2927 <tag-desc>
2928 The number of messages received by this node.
2929 </tag-desc>
2930 <tag-name>
2931 <literal>msgs_out</literal> (<literal>integer</literal>)
2932 </tag-name>
2933 <tag-desc>
2934 The number of messages sent by this node.
2935 </tag-desc>
2936 <tag-name>
2937 <literal>bytes_out</literal> (<literal>integer</literal>)
2938 </tag-name>
2939 <tag-desc>
2940 The number of bytes sent by this node.
2941 </tag-desc>
2942 <tag-name>
2943 <literal>nodes_online</literal> (<literal>integer</literal>)
2944 </tag-name>
2945 <tag-desc>
2946 The number of peers this node is connected to.
2947 </tag-desc>
2948 </list>
2949 </tag-desc>
2950 </list>
2951 <para>Example:</para>
2952 <example>
2953 {
2954 "zones" : {
2955 "zone1" : {
2956 "records_pending" : 2061,
2957 "records_total" : 260575
2958 },
2959 "zone2" : {
2960 "records_pending" : 0,
2961 "records_total" : 14749
2962 }
2963 },
2964 "status" : {
2965 "bytes_in" : 1364923761,
2966 "msgs_in" : 337236,
2967 "msgs_out" : 346717,
2968 "bytes_out" : 1402765472,
2969 "nodes_online" : 15
2970 }
2971 }</example>
2972 </listitem>
2973 <listitem id="def_nginx_stream_zone_sync_zone">
2974 <para>Sync Zone:</para>
2975 Synchronization status of a shared memory zone.<list type="tag">
2976 <tag-name>
2977 <literal>records_pending</literal> (<literal>integer</literal>)
2978 </tag-name>
2979 <tag-desc>
2980 The number of records that need to be sent to the cluster.
2981 </tag-desc>
2982 <tag-name>
2983 <literal>records_total</literal> (<literal>integer</literal>)
2984 </tag-name>
2985 <tag-desc>
2986 The total number of records stored in the shared memory zone.
2987 </tag-desc>
2988 </list>
2989 </listitem>
2881 <listitem id="def_nginx_error"> 2990 <listitem id="def_nginx_error">
2882 <para>Error:</para> 2991 <para>Error:</para>
2883 nginx error object.<list type="tag"> 2992 nginx error object.<list type="tag">
2884 <tag-name> 2993 <tag-name>
2885 <literal>path</literal> (<literal>string</literal>) 2994 <literal>path</literal> (<literal>string</literal>)