Changeset 46d766e7a7e64b0d0718f552ab01b9ba486892c5

Show
Ignore:
Timestamp:
12/16/11 15:49:55 (1 year ago)
Author:
Theo Schlossnagle <jesus@omniti.com>
git-committer:
Theo Schlossnagle <jesus@omniti.com> 1324050595 -0500
git-parent:

[eb91b667acfd9618209c5fc3f666c574f85ef510]

git-author:
Theo Schlossnagle <jesus@omniti.com> 1324050595 -0500
Message:

split out the rest doc to make adding new docs less intimidating

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • docs/docbuild.conf

    r23dea7e r46d766e  
    11# perform code analysis and doc extraction on trunk 
    22# multiple space separated modules of the repos may be specified 
    3 dox trunk 
     3dox src 
    44 

  • docs/operation/wire/rest.xml

    r23dea7e r46d766e  
    1 <?xml version="1.0"?> 
     1<?xml version='1.0' encoding='UTF-8' ?> 
     2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" 
     3  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" 
     4[ 
     5  <!ENTITY % magic.fixup SYSTEM "http://labs.omniti.com/docbook/ent"> 
     6  %magic.fixup; 
     7]> 
    28<section> 
    39<title>REST operation over HTTP</title> 
    …… 
    1622<section> 
    1723<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  
     24&operation.wire.checks.all; 
    14925</section> 
    15026 
    15127<section> 
    15228<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  
     29&operation.wire.filters.all; 
    24230</section> 
    24331</section>