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

{% block description %}

<p>Each API response contains a JSON-encoded object in the HTTP body, which contains 3 attributes:</p>
<ul>
    <li>
        <b>result</b> -
        the actual data returned by the request. May be <tt>null</tt> in case of error.
    </li>
    <li>
        <b>metadata</b> -
        additional information about the result, such as the <a href="../pagination/">pagination</a> information.
    </li>
    <li><b>error</b> - in case of an error, contains a human-readable error message. Otherwise it is <tt>null</tt>.</li>
</ul>

<p>Here is a sample response from a request that ended successfully:</p>

<pre class="prettyprint">
{
    "error": null,
    "result": {
        "serial": 1007,
        "name": "ibox007",
        "version": "1.5.3.2",
        "type": "InfiniBox",
        "api_url": "https://ibox007",
        "api_username": "admin",
        "created": "2016-11-16T13:11:58Z",
        "modified": "2016-12-18T15:06:01Z",
        "monitored_entities": "https://infinimetrics/api/rest/systems/1007/monitored_entities/",
        "annotations": "https://infinimetrics/api/rest/systems/1007/annotations/"
    },
    "metadata": {
        "ready": true
    }
}
</pre>

<p>Here is a sample response from a request that ended with an error:</p>
<pre class="prettyprint">
{
    "error": {
        "message": "Not found"
    },
    "result": null,
    "metadata": {
        "ready": true
    }
}
</pre>

<p>In case of a bad request (HTTP 400), the response also includes an additional list of details:</p>
<pre class="prettyprint">
{
    "error": {
        "message": "Bad request",
        "details": [
            "Unknown filter field: 'color' (choices are serial, name, version, api_url, api_username, created, modified)"
        ]
    },
    "result": null,
    "metadata": {
        "ready": true
    }
}
</pre>

<h3>HTTP Response Codes</h3>

<p>The API returns each response with one of the following HTTP status codes:</p>

<table class="table table-bordered">
    <tbody>
        <tr>
            <th>HTTP 200</th>
            <td>Successful OPTIONS, GET, PUT or PATCH request</td>
        </tr>
        <tr>
            <th>HTTP 201</th>
            <td>Successful POST request</td>
        </tr>
        <tr>
            <th>HTTP 204</th>
            <td>Successful DELETE request</td>
        </tr>
        <tr>
            <th>HTTP 400</th>
            <td>Bad request (e.g. validation failure)</td>
        </tr>
        <tr>
            <th>HTTP 403</th>
            <td>Missing or invalid credentials</td>
        </tr>
        <tr>
            <th>HTTP 404</th>
            <td>Not found</td>
        </tr>
        <tr>
            <th>HTTP 405</th>
            <td>Method not allowed</td>
        </tr>
        <tr>
            <th>HTTP 406</th>
            <td>The request data is in an unsupported content type</td>
        </tr>
    </tbody>
</table>

Next: <a href="/api/docs/pagination/">Pagination &raquo;</a>

{% endblock %}