Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_api_module_head.xml @ 2601:5528961da54d
njs-0.4.4.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 29 Sep 2020 18:22:17 +0100 |
parents | 407147d8020f |
children | 9dd8c203a54a |
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/6/ http://127.0.0.1/api/6/nginx http://127.0.0.1/api/6/connections http://127.0.0.1/api/6/http/requests http://127.0.0.1/api/6/http/server_zones/server_backend http://127.0.0.1/api/6/http/caches/cache_backend http://127.0.0.1/api/6/http/upstreams/backend http://127.0.0.1/api/6/http/upstreams/backend/servers/ http://127.0.0.1/api/6/http/upstreams/backend/servers/1 http://127.0.0.1/api/6/http/keyvals/one?key=arg1 http://127.0.0.1/api/6/stream/ http://127.0.0.1/api/6/stream/server_zones/server_backend http://127.0.0.1/api/6/stream/upstreams/ http://127.0.0.1/api/6/stream/upstreams/backend http://127.0.0.1/api/6/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>6</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/6/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 <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>