{% extends "sentry/help/index.html" %}

{% load i18n %}
{% load sentry_helpers %}

{% block title %}
    Web API
{% endblock %}

{% block breadcrumbs %}
    {{ block.super }}
    <li class="divider">/</li>
    <li><a href="{% url 'sentry-api-0-help' %}">Web API</a></li>
{% endblock%}

{% block main %}
    <h2>Web API</h2>

    <p>You are viewing documention for version 0 of the Sentry web API.</p>

    <ol>
      <li><a href="#current-verison">Current Version</a></li>
      <li><a href="#schema">Schema</a></li>
      <li><a href="#http-verbs">HTTP Verbs</a></li>
      <li><a href="#parameters">Parameters</a></li>
      <li><a href="#authentication">Authentication</a></li>
      <li><a href="#pagination">Pagination</a></li>
    </ol>

    <h3>Current Version</h3>

    <p>The current version of the API is dubbed <strong>v0</strong> and is considered to be in a draft phase. <strong>While we don't expect public endpoints to add change greatly, keep in mind that the API is still under development.</strong></p>

    <h3>Schema</h3>

    <p>All API requests should be made to the /api/0/ prefix, and will return JSON as the response:</p>

    <pre>$ curl -i {{ SENTRY_URL_PREFIX }}/api/0/

  HTTP/1.0 200 OK
  Date: Sat, 14 Feb 2015 18:47:20 GMT
  Server: WSGIServer/0.1 Python/2.7.9
  Vary: Accept-Language, Cookie
  Content-Type: application/json
  Content-Language: en
  Allow: GET, HEAD, OPTIONS

  {"version": "0"}</pre>

    <h3 id="http-verbs">HTTP Verbs</h3>

    <p>Sentry makes an attempt to stick to appropriate verbs, but we always prioritize usability over correctness.</p>

    <table class="table">
      <thead>
        <th>Verb</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>DELETE</td>
          <td>Used for deleting resources.</td>
        </tr>
        <tr>
          <td>GET</td>
          <td>Used for retrieving resources.</td>
        </tr>
        <tr>
          <td>OPTIONS</td>
          <td>Describes the given endpoint.</td>
        </tr>
        <tr>
          <td>POST</td>
          <td>Used for creating resources.</td>
        </tr>
        <tr>
          <td>PUT</td>
          <td>Used for updating resources. Partial data is accepted where possible.</td>
        </tr>
      </tbody>
    </table>

    <h3 id="parameters">Parameters</h3>

    <p>Any parameters not included in the URL should be encoded as JSON with a Content-Type of 'application/json':</p>

    <pre>$ curl -i {{ SENTRY_URL_PREFIX }}/api/0/projects/1/groups/ \
    -d '{"status": "resolved"}' \
    -H 'Content-Type: application/json'</pre>

    <p>Additional parameters are sometimes specified via the querystring, even for POST, PUT, and DELETE requests:</p>

    <pre>$ curl -i {{ SENTRY_URL_PREFIX }}/api/0/projects/1/groups/?status=unresolved \
    -d '{"status": "resolved"}' \
    -H 'Content-Type: application/json'</pre>

    <h3 id="authentication">Authentication</h3>

    <p>API requests are made using project-level API keys. They're passed using HTTP Basic auth where the username is your public key, and the password is your secret key. The API key must also be configured with "Web API access" as a role.</p>

    <p>As an example, to get information about the project which your key is bound to, you might make a request like so:</p>

    <pre>curl -u PUBLIC_KEY:SECRET_KEY {{ SENTRY_URL_PREFIX }}/api/0/projects/1/</pre>

    <p>Note: Currently requests are limited to project-scoped endpoints only.</p>

    <h3 id="pagination">Pagination</h3>

    <p>Pagination in the API is handled via the Link header standard:</p>

    <pre>$ curl -i {{ SENTRY_URL_PREFIX }}/api/0/projects/1/groups/

Link: &lt;{{ SENTRY_URL_PREFIX }}/api/0/projects/1/groups/?&amp;cursor=1420837590:0:1&gt;; rel="previous"; results="false",
      &lt;{{ SENTRY_URL_PREFIX }}/api/0/projects/1/groups/?&amp;cursor=1420837533:0:0&gt;; rel="next"; results="true"</pre>

    <p>In this example we have both a 'previous' link and a 'next' link. The meaning of these links depends on the input query, but in our above example the 'previous' page would be page index -1, and the next page would be page index 1.</p>

    <p>When supported, cursors will <strong>always</strong> be returned for both a previous and a next page, even if there are no results on these pages. This allows you to make a query against the API for yet-undiscovered results. An example where this would be used is when you're implementing polling behavior and you want to see if there is any new data. To help understand if you actually need to paginate we return a <code>results="[true|false]"</code> indicator.</p>


{% endblock %}
