root/docs/operation/wire/rest.xml

Revision 23dea7e00df87480acb58bb3398283c2bb227949, 7.8 kB (checked in by Theo Schlossnagle <jesus@omniti.com>, 3 years ago)

pull docs into master

  • Property mode set to 100644
Line 
1 <?xml version="1.0"?>
2 <section>
3 <title>REST operation over HTTP</title>
4
5 <para>
6 A variety of operational read and write operations are available over
7 HTTP.  The HTTP layer is only available over SSL (HTTPS), operates on
8 the IANA assigned port number 43191.  The SSL implementation of the
9 wire protocol requires client certificates, so this REST mechansim is
10 only available to HTTP clients that support both SSL and user-supplied
11 client certificates.  The client certificates must be signed by a
12 certificate authority recognized by the <command>noitd</command>
13 instance.
14 </para>
15
16 <section>
17 <title>Manipulating Checks</title>
18
19 <section>
20 <title>/checks/show/</title>
21   <variablelist>
22     <varlistentry>
23       <term>method</term>
24       <listitem><code>GET</code></listitem>
25     </varlistentry>
26     <varlistentry>
27       <term>uri</term>
28       <listitem><code>/checks/show/&lt;path/&gt;&lt;checkid&gt;</code></listitem>
29     </varlistentry>
30   </variablelist>
31   <para>
32   This call returns an XML document describing the current configuration and
33   state of the specific check.  The <code>checkid</code> specified is located
34   under the optional <code>path</code>.  If the check exists, but it under
35   another path, a HTTP 403 code is returned.  If the check does not exist,
36   a HTTP 404 code is returned.
37   </para>
38
39   <example>
40     <title>REST /checks/show XML output.</title>
41     <para>Output from an HTTP GET of <code>/checks/show/1b4e28ba-2fa1-11d2-883f-b9a761bde3aa</code></para>
42     <programlisting><![CDATA[
43 <?xml version="1.0" encoding="utf8"?>
44 <check>
45   <attributes>
46     <uuid>1b4e28ba-2fa1-11d2-883f-b9a761bde3aa</uuid>
47     <name>http</name>
48     <module inherited="/dc1/web/@module">http</module>
49     <target>8.8.38.5</target>
50     <period inherited="/dc1/@period">60000</period>
51     <timeout inherited="/dc1/@timeout">5000</timeout>
52     <filterset inherited="/@filterset">default</filterset>
53   </attributes>
54   <config>
55     <code>200</code>
56     <url>https://labs.omniti.com/</url>
57   </config>
58   <state>
59     <running>false</running>
60     <killed>false</killed>
61     <configured>true</configured>
62     <disabled>false</disabled>
63     <last_run now="1253124365.131">1253124339.270</last_run>
64     <runtime>4.408</runtime>
65     <availability>available</availability>
66     <state>good</state>
67     <status>code=200,rt=4.409s,bytes=8958</status>
68     <metrics>
69       <duration type="I">4408</duration>
70       <code type="s">200</code>
71       <bytes type="i">8958</bytes>
72     </metrics>
73   </state>
74 </check>
75     ]]></programlisting>
76   </example>
77 </section>
78
79 <section>
80 <title>/checks/set/</title>
81   <variablelist>
82     <varlistentry>
83       <term>method</term>
84       <listitem><code>PUT</code></listitem>
85     </varlistentry>
86     <varlistentry>
87       <term>uri</term>
88       <listitem><code>/checks/set/&lt;path/&gt;&lt;checkid&gt;</code></listitem>
89     </varlistentry>
90   </variablelist>
91   <para>
92   This call accepts a document describing a check.  That check is
93   instantiated with the <code>checkid</code> specified in the URL.  If the
94   check exists, but is not under the provided optional <code>path</code> a
95   HTTP 403 code is returned.  If the check already exists under the specified
96   <code>path</code>, the check is updated to reflect the new configuration.
97   The <code>module</code> cannot be changed for existing checks.  All other
98   fields can be changed.  All fields are required except the
99   <code>disable</code> field; if disable is omitted, it will inherit the
100   disable attribute from parents in the tree (use the default setting).
101   On success, a HTTP 200 is returned and an XML documented that matches the
102   format of the <code>/check/show</code> REST command.
103   The input is as follows:
104   </para>
105
106   <example>
107     <title>REST /checks/set XML input.</title>
108     <programlisting><![CDATA[
109 <?xml version="1.0" encoding="utf8"?>
110 <check>
111   <attributes>
112     <name>http</name>
113     <module>http</module>
114     <target>8.8.38.5</target>
115     <period>60000</period>
116     <timeout>5000</timeout>
117     <filterset>default</filterset>
118   </attributes>
119   <config>
120     <code>200</code>
121     <url>https://labs.omniti.com/</url>
122   </config>
123 </check>
124     ]]></programlisting>
125   </example>
126 </section>
127 <section>
128 <title>/checks/delete/</title>
129   <variablelist>
130     <varlistentry>
131       <term>method</term>
132       <listitem><code>DELETE</code></listitem>
133     </varlistentry>
134     <varlistentry>
135       <term>uri</term>
136       <listitem><code>/checks/delete/&lt;path/&gt;&lt;checkid&gt;</code></listitem>
137     </varlistentry>
138   </variablelist>
139   <para>
140   This call returns deletes the specified check.  If the check does not
141   exist, then a HTTP 404 code is returned.  If the check exists, but is
142   outside of the optional <code>path</code>, then a HTTP 403 code is
143   returned.  Otherwise, the specified check is removed from the system
144   and a HTTP 200 is returned.  Any response payload returned should be
145   ignored by the client.
146   </para>
147 </section>
148
149 </section>
150
151 <section>
152 <title>Manipulating Filters</title>
153
154 <section>
155 <title>/filters/show/</title>
156   <variablelist>
157     <varlistentry>
158       <term>method</term>
159       <listitem><code>GET</code></listitem>
160     </varlistentry>
161     <varlistentry>
162       <term>uri</term>
163       <listitem><code>/filters/show/&lt;path/&gt;&lt;filterset&gt;</code></listitem>
164     </varlistentry>
165   </variablelist>
166   <para>
167   This call returns an XML document describing the current configuration
168   of the specified filterset.  The <code>filterset</code> specified is located
169   under the optional <code>path</code>.  If the check exists, but it under
170   another path, a HTTP 403 code is returned.  If the check does not exist,
171   a HTTP 404 code is returned.
172   </para>
173
174   <example>
175     <title>REST /filters/show XML output.</title>
176     <para>Output from an HTTP GET of <code>/filters/show/default</code></para>
177     <programlisting><![CDATA[
178 <?xml version="1.0" encoding="utf8"?>
179 <filterset>
180   <rule type="deny" module="^ping_icmp$" metric="^(?:minimum|maximum|count)$"/>
181 </filterset>
182     ]]></programlisting>
183   </example>
184 </section>
185
186 <section>
187 <title>/filters/set/</title>
188   <variablelist>
189     <varlistentry>
190       <term>method</term>
191       <listitem><code>PUT</code></listitem>
192     </varlistentry>
193     <varlistentry>
194       <term>uri</term>
195       <listitem><code>/filters/set/&lt;path/&gt;&lt;filterset&gt;</code></listitem>
196     </varlistentry>
197   </variablelist>
198   <para>
199   This call accepts a document describing a filterset.  That filterset is
200   instantiated with the name <code>filterset</code> specified in the URL.
201   If the filterset exists, but is not under the provided optional
202   <code>path</code> a HTTP 403 code is returned.  If the filterset already
203   exists under the specified <code>path</code>, the filterset is replaced
204   with the configuration submitted.
205   On success, a HTTP 200 is returned and an XML documented that matches the
206   format of the <code>/check/show</code> REST command.
207   The input is as follows:
208   </para>
209
210   <example>
211     <title>REST /filtert/set XML input.</title>
212     <programlisting><![CDATA[
213 <?xml version="1.0" encoding="utf8"?>
214 <filterset>
215   <rule type="deny" module="^ping_icmp$" metric="^(?:minimum|maximum|count)$"/>
216 </filterset>
217     ]]></programlisting>
218   </example>
219 </section>
220 <section>
221 <title>/filters/delete/</title>
222   <variablelist>
223     <varlistentry>
224       <term>method</term>
225       <listitem><code>DELETE</code></listitem>
226     </varlistentry>
227     <varlistentry>
228       <term>uri</term>
229       <listitem><code>/filters/delete/&lt;path/&gt;&lt;filterset&gt;</code></listitem>
230     </varlistentry>
231   </variablelist>
232   <para>
233   This call returns deletes the specified filterset.  If the filterset does
234   not exist, then a HTTP 404 code is returned.  If the filterset exists, but
235   is outside of the optional <code>path</code>, then a HTTP 403 code is
236   returned.  Otherwise, the specified filterset is removed from the system
237   and a HTTP 200 is returned.  Any response payload returned should be
238   ignored by the client.
239   </para>
240 </section>
241
242 </section>
243 </section>
Note: See TracBrowser for help on using the browser.