<?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>