root/docs/operation/wire/rest.xml

<?xml version="1.0"?>
<section>
<title>REST operation over HTTP</title>

<para>
A variety of operational read and write operations are available over
HTTP.  The HTTP layer is only available over SSL (HTTPS), operates on
the IANA assigned port number 43191.  The SSL implementation of the
wire protocol requires client certificates, so this REST mechansim is
only available to HTTP clients that support both SSL and user-supplied
client certificates.  The client certificates must be signed by a
certificate authority recognized by the <command>noitd</command>
instance.
</para>

<section>
<title>Manipulating Checks</title>

<section>
<title>/checks/show/</title>
  <variablelist>
    <varlistentry>
      <term>method</term>
      <listitem><code>GET</code></listitem>
    </varlistentry>
    <varlistentry>
      <term>uri</term>
      <listitem><code>/checks/show/&lt;path/&gt;&lt;checkid&gt;</code></listitem>
    </varlistentry>
  </variablelist>
  <para>
  This call returns an XML document describing the current configuration and
  state of the specific check.  The <code>checkid</code> specified is located
  under the optional <code>path</code>.  If the check exists, but it under
  another path, a HTTP 403 code is returned.  If the check does not exist,
  a HTTP 404 code is returned.
  </para>

  <example>
    <title>REST /checks/show XML output.</title>
    <para>Output from an HTTP GET of <code>/checks/show/1b4e28ba-2fa1-11d2-883f-b9a761bde3aa</code></para>
    <programlisting><![CDATA[
<?xml version="1.0" encoding="utf8"?>
<check>
  <attributes>
    <uuid>1b4e28ba-2fa1-11d2-883f-b9a761bde3aa</uuid>
    <name>http</name>
    <module inherited="/dc1/web/@module">http</module>
    <target>8.8.38.5</target>
    <period inherited="/dc1/@period">60000</period>
    <timeout inherited="/dc1/@timeout">5000</timeout>
    <filterset inherited="/@filterset">default</filterset>
  </attributes>
  <config>
    <code>200</code>
    <url>https://labs.omniti.com/</url>
  </config>
  <state>
    <running>false</running>
    <killed>false</killed>
    <configured>true</configured>
    <disabled>false</disabled>
    <last_run now="1253124365.131">1253124339.270</last_run>
    <runtime>4.408</runtime>
    <availability>available</availability>
    <state>good</state>
    <status>code=200,rt=4.409s,bytes=8958</status>
    <metrics>
      <duration type="I">4408</duration>
      <code type="s">200</code>
      <bytes type="i">8958</bytes>
    </metrics>
  </state>
</check>
    ]]></programlisting>
  </example>
</section>

<section>
<title>/checks/set/</title>
  <variablelist>
    <varlistentry>
      <term>method</term>
      <listitem><code>PUT</code></listitem>
    </varlistentry>
    <varlistentry>
      <term>uri</term>
      <listitem><code>/checks/set/&lt;path/&gt;&lt;checkid&gt;</code></listitem>
    </varlistentry>
  </variablelist>
  <para>
  This call accepts a document describing a check.  That check is
  instantiated with the <code>checkid</code> specified in the URL.  If the
  check exists, but is not under the provided optional <code>path</code> a
  HTTP 403 code is returned.  If the check already exists under the specified
  <code>path</code>, the check is updated to reflect the new configuration.
  The <code>module</code> cannot be changed for existing checks.  All other
  fields can be changed.  All fields are required except the
  <code>disable</code> field; if disable is omitted, it will inherit the
  disable attribute from parents in the tree (use the default setting).
  On success, a HTTP 200 is returned and an XML documented that matches the
  format of the <code>/check/show</code> REST command.
  The input is as follows:
  </para>

  <example>
    <title>REST /checks/set XML input.</title>
    <programlisting><![CDATA[
<?xml version="1.0" encoding="utf8"?>
<check>
  <attributes>
    <name>http</name>
    <module>http</module>
    <target>8.8.38.5</target>
    <period>60000</period>
    <timeout>5000</timeout>
    <filterset>default</filterset>
  </attributes>
  <config>
    <code>200</code>
    <url>https://labs.omniti.com/</url>
  </config>
</check>
    ]]></programlisting>
  </example>
</section>
<section>
<title>/checks/delete/</title>
  <variablelist>
    <varlistentry>
      <term>method</term>
      <listitem><code>DELETE</code></listitem>
    </varlistentry>
    <varlistentry>
      <term>uri</term>
      <listitem><code>/checks/delete/&lt;path/&gt;&lt;checkid&gt;</code></listitem>
    </varlistentry>
  </variablelist>
  <para>
  This call returns deletes the specified check.  If the check does not
  exist, then a HTTP 404 code is returned.  If the check exists, but is
  outside of the optional <code>path</code>, then a HTTP 403 code is
  returned.  Otherwise, the specified check is removed from the system
  and a HTTP 200 is returned.  Any response payload returned should be
  ignored by the client.
  </para>
</section>

</section>

<section>
<title>Manipulating Filters</title>

<section>
<title>/filters/show/</title>
  <variablelist>
    <varlistentry>
      <term>method</term>
      <listitem><code>GET</code></listitem>
    </varlistentry>
    <varlistentry>
      <term>uri</term>
      <listitem><code>/filters/show/&lt;path/&gt;&lt;filterset&gt;</code></listitem>
    </varlistentry>
  </variablelist>
  <para>
  This call returns an XML document describing the current configuration 
  of the specified filterset.  The <code>filterset</code> specified is located
  under the optional <code>path</code>.  If the check exists, but it under
  another path, a HTTP 403 code is returned.  If the check does not exist,
  a HTTP 404 code is returned.
  </para>

  <example>
    <title>REST /filters/show XML output.</title>
    <para>Output from an HTTP GET of <code>/filters/show/default</code></para>
    <programlisting><![CDATA[
<?xml version="1.0" encoding="utf8"?>
<filterset>
  <rule type="deny" module="^ping_icmp$" metric="^(?:minimum|maximum|count)$"/>
</filterset>
    ]]></programlisting>
  </example>
</section>

<section>
<title>/filters/set/</title>
  <variablelist>
    <varlistentry>
      <term>method</term>
      <listitem><code>PUT</code></listitem>
    </varlistentry>
    <varlistentry>
      <term>uri</term>
      <listitem><code>/filters/set/&lt;path/&gt;&lt;filterset&gt;</code></listitem>
    </varlistentry>
  </variablelist>
  <para>
  This call accepts a document describing a filterset.  That filterset is
  instantiated with the name <code>filterset</code> specified in the URL.
  If the filterset exists, but is not under the provided optional
  <code>path</code> a HTTP 403 code is returned.  If the filterset already
  exists under the specified <code>path</code>, the filterset is replaced
  with the configuration submitted.
  On success, a HTTP 200 is returned and an XML documented that matches the
  format of the <code>/check/show</code> REST command.
  The input is as follows:
  </para>

  <example>
    <title>REST /filtert/set XML input.</title>
    <programlisting><![CDATA[
<?xml version="1.0" encoding="utf8"?>
<filterset>
  <rule type="deny" module="^ping_icmp$" metric="^(?:minimum|maximum|count)$"/>
</filterset>
    ]]></programlisting>
  </example>
</section>
<section>
<title>/filters/delete/</title>
  <variablelist>
    <varlistentry>
      <term>method</term>
      <listitem><code>DELETE</code></listitem>
    </varlistentry>
    <varlistentry>
      <term>uri</term>
      <listitem><code>/filters/delete/&lt;path/&gt;&lt;filterset&gt;</code></listitem>
    </varlistentry>
  </variablelist>
  <para>
  This call returns deletes the specified filterset.  If the filterset does
  not exist, then a HTTP 404 code is returned.  If the filterset exists, but
  is outside of the optional <code>path</code>, then a HTTP 403 code is
  returned.  Otherwise, the specified filterset is removed from the system
  and a HTTP 200 is returned.  Any response payload returned should be
  ignored by the client.
  </para>
</section>

</section>
</section>