{% extends "rest_framework/api_basics.html" %}

{% block description %}
<h3>Authentication</h3>

<p>General pages require credentials for any system or IMX_ADMIN.</p>
<p>Pages of a specific system require credentials for the system or IMX_ADMIN.</p>

<h3>Simple Requests</h3>

<p>Getting a list of all systems being monitored by InfiniMetrics:</p>
<pre>
curl -u username:password https://infinimetrics/api/rest/systems/
</pre>

<p>Getting a single system with serial number 10017:</p>
<pre>
curl -u username:password https://infinimetrics/api/rest/systems/10017/
</pre>

<p>Getting any annotations defined for the system:</p>
<pre>
curl -u username:password https://infinimetrics/api/rest/systems/10017/annotations/
</pre>


<h3>Controlling the Response Format</h3>

<p>The default <a href="/api/docs/format/">response format</a> is JSON, so the following three commands are equivalent:</p>
<pre>
curl -u username:password https://infinimetrics/api/rest/systems/
curl -u username:password https://infinimetrics/api/rest/systems/?format=json
curl -u username:password --header "Accept: application/json" https://infinimetrics/api/rest/systems/
</pre>

<p>The <code>Accept</code> header can include an <code>indent</code> media type parameter, in which case the returned JSON will be formatted nicely:</p>
<pre>
curl -u username:password --header "Accept: application/json; indent=4" https://infinimetrics/api/rest/systems/
</pre>

<p>To get a response in <a href="/api/docs/csv/">CSV format</a>, use one of the following options:</p>
<pre>
curl -u username:password https://infinimetrics/api/rest/systems/?format=csv
curl -u username:password --header "Accept: text/csv" https://infinimetrics/api/rest/systems/
</pre>


<h3>Filtering and Sorting</h3>

<p>Searching for a system with a specific name:</p>
<pre>
curl -u username:password https://infinimetrics/api/rest/systems/?name=mybox
</pre>

<p>Searching for annotations containing some text, sorting the results latest first:</p>
<pre>
curl -u username:password https://infinimetrics/api/rest/systems/10017/annotations/?description=like:backup&sort=-timestamp
</pre>

<p>For additional details see <a href="/api/docs/filtering/">Filtering</a> and <a href="/api/docs/sorting/">Sorting</a>.</p>


<h3>Updating System Credentials</h3>

<p>Use a <code>PATCH</code> request to make changes to an existing system. The request payload can be sent as JSON,
in which case you must specify that the content type is <code>application/json</code>.
The credentials after the <code>--user</code> are for authentication against the system.
The credentials after the <code>--data</code> are the new credentials InfiniMetrics will use to monitor this system:</p>
<pre>
curl --user username:password \
     --request PATCH \
     --header "Content-Type: application/json" \
     --data '{"api_username": "admin", "api_password": "g6BT0acS"}' \
     https://infinimetrics/api/rest/systems/10017/
</pre>

<p>Alternatively you may use the <code>application/x-www-form-urlencoded</code> encoding, which is the default in curl:</p>
<pre>
curl --user username:password \
     --request PATCH \
     --data 'api_username=admin&api_password=g6BT0acS' \
     https://infinimetrics/api/rest/systems/10017/
</pre>


<h3>Starting to Monitor a Volume or Filesystem</h3>

<p>Send a <code>POST</code> request containing 3 fields:</p>
<ul>
    <li><b>type</b> - either "Volume" or "Filesystem"</li>
    <li><b>name</b> or <b>id_in_system</b> - to identify the entity</li>
    <li><b>polling_interval</b> - 10, 30, 60, or 300 seconds</li>
</ul>

<pre>
curl --request POST \
     -u username:password \
     --header "Content-Type: application/json" \
     --data '{"type": "Volume", "name": "my_volume", "polling_interval": 10}' \
     https://infinimetrics/api/rest/systems/10017/monitored_entities/

curl --request POST \
     -u username:password \
     --header "Content-Type: application/json" \
     --data '{"type": "Filesystem", "id_in_system": 95644, "polling_interval": 30}' \
     https://infinimetrics/api/rest/systems/10017/monitored_entities/
</pre>

<h3>Adding an Annotation</h3>

<p>Creating a new annotation is done with a <code>POST</code> request:</p>
<pre>
curl --request POST \
     -u username:password \
     --header "Content-Type: application/json" \
     --data '{"description": "Starting database backup", "marker_style": "purple"}' \
     https://infinimetrics/api/rest/systems/10017/annotations/
</pre>
<p>In case the annotation timestamp isn't specified, the current time and date is used.</p>


<h3>Downloading Collected Data</h3>

<p>Getting the latest 3 records collected for a monitored entity:
<pre>
curl -u username:password https://infinimetrics/api/rest/systems/10017/monitored_entities/1/data/?sort=-timestamp&page_size=3
</pre>

<p>
To download large amounts of data you need to write code that handles pagination. For maximum efficiency,
use <a href="/api/docs/csv/">CSV format</a> and set the <code>page_size</code> to its maximum value (10000).
The following Python code demonstrates how to download all records between two dates and save them to a file:
</p>
<pre class="prettyprint">
{% include "rest_framework/example_data_download.py" %}
</pre>


{% endblock %}