NewsBlur/templates/static/api.xhtml

{% extends 'base.html' %}

{% block bodyclass %}NB-static NB-static-api{% endblock %}

{% block content %}

  <div class="NB-static-title">
    The NewsBlur API
  </div>


  {# ========= #}
  {# = Feeds = #}
  {# ========= #}
  
  
  <div class="NB-module">
    <h5 class="NB-module-title">API Guidelines and Terms of Service</h5>
    <div class="NB-module-content">
      <p>NewsBlur's API allows users to retrieve their feeds, feed counts, feed icons, feed
      statistics, and individual feed stories. No API key is required, but you are required
      to authenticate before using any of the API endpoints. Please be considerate, and don't
      hammer our servers.</p>
      
       <p>If your project or application allows users to interact with data from NewsBlur,
      you must cite NewsBlur as the source of your data.</p>
      
       <p>You may use the API commercially, by which we mean you may charge people money to
      use your project which itself uses the API. You may not, however, sell advertising
      against any data retrieved from NewsBlur's API. Essentially, you can charge money for
      your application or service, but not wrap NewsBlur in advertisements.</p>
      
       <p><i>We reserve the right to revise these guidelines. If you violate the spirit of
      these terms, expect to be blocked without advance warning.</i></p>
    </div>
  </div>

  <div class="NB-module">
    <h5 class="NB-module-title">Feeds</h5>
    <div class="NB-module-content">
      
      
      <h3><tt>GET /api/1/reader/feeds</tt></h3>
      
      <p>Retrieve a user's list of feeds. Includes the 3 unread counts, as well as optional
      favicons.</p>
      
      <table>
        <tr>
          <th>Parameter</th>
          <th>Description</th>
          <th>Default</th>
          <th>Example</th>
        </tr>
        <tr>
          <td>include_favicons</td>
          <td><span class="optional">Optional</span> Include favicons inline. Since they can be time consuming to
          download, you can optionally turn them off. Use <tt>/api/1/feeds/favicons/</tt> to retrieve the favicons
          in a separate request.</td>
          <td><code>true</code></td>
          <td><code>true/false</code></td>
        </tr>
      </table>

      <h4>Example Response</h4>
      
      <pre><code>
{
  'feeds': []
}
      </code></pre>
      
      <h4>Tips</h4>
      
      <ul>
        <li>Use <code>/api/1/reader/refresh_feeds</code> to get updated unread counts.</li>
        <li>Turn off <code>include_favicons</code> if you can either cache favicons or can wait to fetch them.</li>
      </ul>



      <h3><tt>GET /api/1/feeds/favicons</tt></h3>
      
      <p>Retrieve a list of favicons for a list of feeds. Used when combined with
      <tt>/api/1/reader/feed_list</tt> and <tt>include_favicons=false</tt>, so the feed_list
      request contains far less data. Useful for mobile devices, but requires a second
      request.</p>
      
      <table>
        <tr>
          <th>Parameter</th>
          <th>Description</th>
          <th>Default</th>
          <th>Example</th>
        </tr>
        <tr>
          <td>feeds</td>
          <td><span class="required">REQUIRED</span> Array of feed ids</td>
          <td></td>
          <td><code>[1, 2, 3]</code></td>
        </tr>
      </table>

      <h4>Example Response</h4>
      
      <pre><code>
{
  'feeds': []
}
      </code></pre>
      
      <h4>Tips</h4>
      
      <ul>
        <li>To use inline data images, you can use this syntax:
          <pre><code>
&lt;img src="data:image/png;base64,[IMAGE_DATA_STRING]" /&gt;
          </code></pre>
        </li>
      </ul>
      
      
      <h3><tt>GET /api/1/reader/feed/:id</tt></h3>
      
      <p>Retrieve stories from a single feed.</p>
      
      <table>
        <tr>
          <th>Parameter</th>
          <th>Description</th>
          <th>Default</th>
          <th>Example</th>
        </tr>
        <tr>
          <td>page</td>
          <td><span class="optional">optional</span> Page of stories, starting from 1.</td>
          <td><code>1</code></td>
          <td><code>12</code></td>
        </tr>
      </table>

      <h4>Example Response</h4>
      
      <pre><code>
{
  'feeds': []
}
      </code></pre>
      
    </div>
  </div>
  
  
  {# =========== #}
  {# = Stories = #}
  {# =========== #}


  <div class="NB-module">
    <h5 class="NB-module-title">Stories</h5>
    <div class="NB-module-content">
      
      
      <h3><tt>GET /api/1/reader/feeds</tt></h3>
      
      <p>Retrieve a user's list of feeds. Includes the 3 unread counts, as well as optional
      favicons.</p>
      
      <table>
        <tr>
          <th>Parameter</th>
          <th>Description</th>
          <th>Default</th>
          <th>Example</th>
        </tr>
        <tr>
          <td>include_favicons</td>
          <td><span class="optional">Optional</span> Include favicons inline. Since they can be time consuming to
          download, you can optionally turn them off. Use <tt>/api/1/feeds/favicons/</tt> to retrieve the favicons
          in a separate request.</td>
          <td><code>true</code></td>
          <td><code>true/false</code></td>
        </tr>
      </table>

      <h4>Example Response</h4>
      
      <pre><code>
{
  'feeds': []
}
      </code></pre>

    </div>
  </div>
  
  
  {# ================ #}
  {# = Intelligence = #}
  {# ================ #}
  
  <div class="NB-module">
    <h5 class="NB-module-title">Intelligence</h5>
    <div class="NB-module-content">
      
      
      <h3><tt>GET /api/1/reader/feeds</tt></h3>
      
      <p>Retrieve a user's list of feeds. Includes the 3 unread counts, as well as optional
      favicons.</p>
      
      <table>
        <tr>
          <th>Parameter</th>
          <th>Description</th>
          <th>Default</th>
          <th>Example</th>
        </tr>
        <tr>
          <td>include_favicons</td>
          <td><span class="optional">Optional</span> Include favicons inline. Since they can be time consuming to
          download, you can optionally turn them off. Use <tt>/api/1/feeds/favicons/</tt> to retrieve the favicons
          in a separate request.</td>
          <td><code>true</code></td>
          <td><code>true/false</code></td>
        </tr>
      </table>

      <h4>Example Response</h4>
      
      <pre><code>
{
  'feeds': []
}
      </code></pre>

    </div>
  </div>
{% endblock content %}