Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_api_module_head.xml @ 2846:fdf1464e1977
Moved banner to the external file to make partial rollout possible.
An idea is to have several banners and show them with different probability
specified by split directive in the nginx.conf
author | Sergey Budnevitch <sb@waeme.net> |
---|---|
date | Tue, 10 May 2022 18:07:27 +0400 |
parents | 9dd8c203a54a |
children | 8bd6f772005f |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Module ngx_http_api_module" link="/en/docs/http/ngx_http_api_module.html" lang="en" rev="3"> <section id="summary"> <para> The <literal>ngx_http_api_module</literal> module (1.13.3) provides REST API for accessing various status information, configuring upstream server groups on-the-fly, and managing <link doc="ngx_http_keyval_module.xml">key-value pairs</link> without the need of reconfiguring nginx. </para> <para> <note> The module supersedes the <link doc="ngx_http_status_module.xml">ngx_http_status_module</link> and <link doc="ngx_http_upstream_conf_module.xml">ngx_http_upstream_conf_module</link> modules. </note> </para> <para> When using the <literal>PATCH</literal> or <literal>POST</literal> methods, make sure that the payload does not exceed the <link doc="ngx_http_core_module.xml" id="client_body_buffer_size">buffer size</link> for reading the client request body, otherwise, the <http-status code="413" text="Request Entity Too Large"/> error may be returned. </para> <para> <note> This module is available as part of our <commercial_version>commercial subscription</commercial_version>. </note> </para> </section> <section id="example" name="Example Configuration"> <para> <example> http { upstream backend { zone http_backend 64k; server backend1.example.com weight=5; server backend2.example.com; } proxy_cache_path /data/nginx/cache_backend keys_zone=cache_backend:10m; server { server_name backend.example.com; location / { proxy_pass http://backend; proxy_cache cache_backend; health_check; } status_zone server_backend; } keyval_zone zone=one:32k state=one.keyval; keyval $arg_text $text zone=one; server { listen 127.0.0.1; location /api { <emphasis>api</emphasis> write=on; allow 127.0.0.1; deny all; } } } stream { upstream backend { zone stream_backend 64k; server backend1.example.com:12345 weight=5; server backend2.example.com:12345; } server { listen 127.0.0.1:12345; proxy_pass backend; status_zone server_backend; health_check; } } </example> All API requests include a supported API <link id="api_version">version</link> in the URI. Examples of API requests with this configuration: <example> http://127.0.0.1/api/7/ http://127.0.0.1/api/7/nginx http://127.0.0.1/api/7/connections http://127.0.0.1/api/7/http/requests http://127.0.0.1/api/7/http/server_zones/server_backend http://127.0.0.1/api/7/http/caches/cache_backend http://127.0.0.1/api/7/http/upstreams/backend http://127.0.0.1/api/7/http/upstreams/backend/servers/ http://127.0.0.1/api/7/http/upstreams/backend/servers/1 http://127.0.0.1/api/7/http/keyvals/one?key=arg1 http://127.0.0.1/api/7/stream/ http://127.0.0.1/api/7/stream/server_zones/server_backend http://127.0.0.1/api/7/stream/upstreams/ http://127.0.0.1/api/7/stream/upstreams/backend http://127.0.0.1/api/7/stream/upstreams/backend/servers/1 </example> </para> </section> <section id="directives" name="Directives"> <directive name="api"> <syntax> [<literal>write</literal>=<literal>on</literal>|<literal>off</literal>]</syntax> <default/> <context>location</context> <para> Turns on the REST API interface in the surrounding location. Access to this location should be <link doc="ngx_http_core_module.xml" id="satisfy">limited</link>. </para> <para> The <literal>write</literal> parameter determines whether the API is read-only or read-write. By default, the API is read-only. </para> <para id="api_version"> All API requests should contain a supported API version in the URI. If the request URI equals the location prefix, the list of supported API versions is returned. The current API version is “<literal>7</literal>”. </para> <para> The optional “<literal>fields</literal>” argument in the request line specifies which fields of the requested objects will be output: <example> http://127.0.0.1/api/7/nginx?fields=version,build </example> </para> </directive> <directive name="status_zone"> <syntax><value>zone</value></syntax> <default/> <context>server</context> <context>location</context> <context>if in location</context> <appeared-in>1.13.12</appeared-in> <para> Enables collection of virtual <link doc="ngx_http_core_module.xml" id="server">http</link> or <link doc="../stream/ngx_stream_core_module.xml" id="server">stream</link> server status information in the specified <value>zone</value>. Several servers may share the same zone. </para> <para id="status_zone_location"> Starting from 1.17.0, status information can be collected per <link doc="ngx_http_core_module.xml" id="location"/>. The special value <literal>off</literal> disables statistics collection in nested location blocks. Note that the statistics is collected in the context of a location where processing ends. It may be different from the original location, if an <link doc="ngx_http_core_module.xml" id="internal">internal redirect</link> happens during request processing. </para> </directive> </section> <section id="compatibility" name="Compatibility"> <para> <list type="bullet"> <listitem> The <literal>codes</literal> data in <literal>responses</literal> for each HTTP <link id="def_nginx_http_upstream">upstream</link>, <link id="def_nginx_http_server_zone">server zone</link>, and <link id="def_nginx_http_location_zone">location zone</link> were added in <link id="api_version">version</link> 7. </listitem> <listitem> The <link id="stream_limit_conns_">/stream/limit_conns/</link> data were added in <link id="api_version">version</link> 6. </listitem> <listitem> The <link id="http_limit_conns_">/http/limit_conns/</link> data were added in <link id="api_version">version</link> 6. </listitem> <listitem> The <link id="http_limit_reqs_">/http/limit_reqs/</link> data were added in <link id="api_version">version</link> 6. </listitem> <listitem> The “<literal>expire</literal>” parameter of a <link doc="ngx_http_keyval_module.xml">key-value</link> pair can be <link id="postHttpKeyvalZoneData">set</link> or <link id="patchHttpKeyvalZoneKeyValue">changed</link> since <link id="api_version">version</link> 5. </listitem> <listitem> The <link id="resolvers_">/resolvers/</link> data were added in <link id="api_version">version</link> 5. </listitem> <listitem> The <link id="http_location_zones_">/http/location_zones/</link> data were added in <link id="api_version">version</link> 5. </listitem> <listitem> The <literal>path</literal> and <literal>method</literal> fields of <link id="def_nginx_error">nginx error object</link> were removed in <link id="api_version">version</link> 4. These fields continue to exist in earlier api versions, but show an empty value. </listitem> <listitem> The <link id="stream_zone_sync_">/stream/zone_sync/</link> data were added in <link id="api_version">version</link> 3. </listitem> <listitem> The <link id="def_nginx_http_upstream_conf_server">drain</link> parameter was added in <link id="api_version">version</link> 2. </listitem> <listitem> The <link id="stream_keyvals_">/stream/keyvals/</link> data were added in <link id="api_version">version</link> 2. </listitem> </list> </para> </section>