Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_api_module_head.xml @ 2028:5c55b7054b58
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> |