Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_api_module_head.xml @ 2206:5cacd6fffade
Eliminated some examples of unsafe prefix locations.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Fri, 27 Apr 2018 09:59:51 +0300 |
parents | f6e578b1b02d |
children | 45a2b90247ad |
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="1"> <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> <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/3/ http://127.0.0.1/api/3/nginx http://127.0.0.1/api/3/connections http://127.0.0.1/api/3/http/requests http://127.0.0.1/api/3/http/server_zones/server_backend http://127.0.0.1/api/3/http/caches/cache_backend http://127.0.0.1/api/3/http/upstreams/backend http://127.0.0.1/api/3/http/upstreams/backend/servers/ http://127.0.0.1/api/3/http/upstreams/backend/servers/1 http://127.0.0.1/api/3/http/keyvals/one?key=arg1 http://127.0.0.1/api/3/stream/ http://127.0.0.1/api/3/stream/server_zones/server_backend http://127.0.0.1/api/3/stream/upstreams/ http://127.0.0.1/api/3/stream/upstreams/backend http://127.0.0.1/api/3/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>3</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/3/nginx?fields=version,build </example> </para> </directive> </section> <section id="compatibility" name="Compatibility"> <para> <list type="bullet"> <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>