Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_api_module_head.xml @ 2028:5c55b7054b58

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 Sat, 26 Aug 2017 00:56:05 +0300
parents
children fee7627f6a5a
comparison
equal deleted inserted replaced
2027:dabca59da4ce 2028:5c55b7054b58
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Nginx, Inc.
5 -->
6
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
8
9 <module name="Module ngx_http_api_module"
10 link="/en/docs/http/ngx_http_api_module.html"
11 lang="en"
12 rev="1">
13
14 <section id="summary">
15
16 <para>
17 The <literal>ngx_http_api_module</literal> module (1.13.3) provides REST API
18 for accessing various status information,
19 configuring upstream server groups on-the-fly, and managing
20 <link doc="ngx_http_keyval_module.xml">key-value pairs</link>
21 without the need of reconfiguring nginx.
22 </para>
23
24 <para>
25 <note>
26 The module supersedes the
27 <link doc="ngx_http_status_module.xml">ngx_http_status_module</link> and
28 <link doc="ngx_http_upstream_conf_module.xml">ngx_http_upstream_conf_module</link>
29 modules.
30 </note>
31 </para>
32
33 <para>
34 <note>
35 This module is available as part of our
36 <commercial_version>commercial subscription</commercial_version>.
37 </note>
38 </para>
39
40 </section>
41
42
43 <section id="example" name="Example Configuration">
44
45 <para>
46 <example>
47 http {
48 upstream backend {
49 zone http_backend 64k;
50
51 server backend1.example.com weight=5;
52 server backend2.example.com;
53 }
54
55 proxy_cache_path /data/nginx/cache_backend keys_zone=cache_backend:10m;
56
57 server {
58 server_name backend.example.com;
59
60 location / {
61 proxy_pass http://backend;
62 proxy_cache cache_backend;
63
64 health_check;
65 }
66
67 status_zone server_backend;
68 }
69
70 keyval_zone zone=one:32k state=one.keyval;
71 keyval $arg_text $text zone=one;
72
73 server {
74 listen 127.0.0.1;
75
76 location /api {
77 <emphasis>api</emphasis> write=on;
78 allow 127.0.0.1;
79 deny all;
80 }
81 }
82 }
83
84 stream {
85 upstream backend {
86 zone stream_backend 64k;
87
88 server backend1.example.com:12345 weight=5;
89 server backend2.example.com:12345;
90 }
91
92 server {
93 listen 127.0.0.1:12345;
94 proxy_pass backend;
95 status_zone server_backend;
96 health_check;
97 }
98 }
99 </example>
100 All API requests include a supported API version in the URI.
101 Examples of API requests with this configuration:
102 <example>
103 http://127.0.0.1/api/1/
104 http://127.0.0.1/api/1/nginx
105 http://127.0.0.1/api/1/connections
106 http://127.0.0.1/api/1/http/requests
107 http://127.0.0.1/api/1/http/server_zones/server_backend
108 http://127.0.0.1/api/1/http/caches/cache_backend
109 http://127.0.0.1/api/1/http/upstreams/backend
110 http://127.0.0.1/api/1/http/upstreams/backend/servers/
111 http://127.0.0.1/api/1/http/upstreams/backend/servers/1
112 http://127.0.0.1/api/1/http/keyvals/one?key=arg1
113 http://127.0.0.1/api/1/stream/
114 http://127.0.0.1/api/1/stream/server_zones/server_backend
115 http://127.0.0.1/api/1/stream/upstreams/
116 http://127.0.0.1/api/1/stream/upstreams/backend
117 http://127.0.0.1/api/1/stream/upstreams/backend/servers/1
118 </example>
119 </para>
120
121 </section>
122
123
124 <section id="directives" name="Directives">
125
126 <directive name="api">
127 <syntax>
128 [<literal>write</literal>=<literal>on</literal>|<literal>off</literal>]</syntax>
129 <default/>
130 <context>location</context>
131
132 <para>
133 Turns on the REST API interface in the surrounding location.
134 Access to this location should be
135 <link doc="ngx_http_core_module.xml" id="satisfy">limited</link>.
136 </para>
137
138 <para>
139 The <literal>write</literal> parameter determines whether the API
140 is read-only or read-write.
141 By default, the API is read-only.
142 </para>
143
144 <para>
145 All API requests should contain a supported API version in the URI.
146 If the request URI equals the location prefix,
147 the list of supported API versions is returned.
148 The current and the only API version is “<literal>1</literal>”.
149 </para>
150
151 <para>
152 The optional “<literal>fields</literal>” argument in the request line
153 specifies which fields of the requested objects will be output:
154 <example>
155 http://127.0.0.1/api/1/nginx?fields=version,build
156 </example>
157 </para>
158
159 </directive>
160
161 </section>