mirror of
https://github.com/samuelclay/NewsBlur.git
synced 2025-04-13 09:42:01 +00:00
173 lines
7 KiB
HTML
173 lines
7 KiB
HTML
{% extends 'base.html' %}
|
|
|
|
{% load utils_tags %}
|
|
|
|
{% block bodyclass %}NB-static NB-static-api{% endblock %}
|
|
|
|
{% block title %}The NewsBlur API{% endblock %}
|
|
|
|
{% block content %}
|
|
|
|
<div class="NB-static-title">
|
|
The NewsBlur API
|
|
</div>
|
|
|
|
|
|
<div class="NB-module">
|
|
<h5 class="NB-module-title">Introduction to the API</h5>
|
|
<div class="NB-module-content">
|
|
<p><a href="/">NewsBlur</a> is a personal news reader that brings people together to
|
|
talk about the world. A new sound of an old instrument.</p>
|
|
<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>We're quite pleased to point out that this entire API is open-source, including
|
|
the implementation of the endpoints. You can find the source of the
|
|
<a href="http://github.com/samuelclay/NewsBlur/tree/master/apps/reader/views.py">/reader/ views source</a>,
|
|
<a href="http://github.com/samuelclay/NewsBlur/tree/master/apps/social/views.py">/social/ views source</a>,
|
|
<a href="http://github.com/samuelclay/NewsBlur/tree/master/apps/rss_feeds/views.py">/rss_feeds/ views source</a>,
|
|
as well as
|
|
<a href="http://github.com/samuelclay/NewsBlur/tree/master/templates/static/api.yml">the API definitions in YAML</a>.</p>
|
|
<p>We love pull requests. If you want to add an endpoint, modify output, or make
|
|
something better, <a href="http://github.com/samuelclay/NewsBlur">NewsBlur's repo
|
|
on Github</a> is the place to make that happen.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="NB-module">
|
|
<h5 class="NB-module-title">A Note about OAuth</h5>
|
|
<div class="NB-module-content">
|
|
<p>NewsBlur supports OAuth but to have an OAuth enabled client you must
|
|
<a href="mailto:samuel@newsblur.com">email Samuel</a> to request a client ID and
|
|
secret. You will need to provide your NewsBlur username, redirect URI (often just your
|
|
client app's website), and app name.</p>
|
|
|
|
<p>To use OAuth when authenticating requests, be sure to pass the Bearer HTTP header with
|
|
every request, just as you would on any other OAuth API. Use the <code>/oauth/authorize</code>
|
|
endpoint to begin the OAuth authentication procedure. Use the <code>/oauth/token</code>
|
|
endpoint to receive your authorized token, which you can pass in with every request.</p>
|
|
|
|
<p>You are not required to use OAuth, in which case you will need to pass the <code>newsblur_sessionid</code>
|
|
cookie with every request. This cookie is set on <a href="#/api/login">login</a>.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="NB-module">
|
|
<h5 class="NB-module-title">API Table of Contents</h5>
|
|
|
|
<div class="NB-module-content">
|
|
<div class="NB-api-endpoint">
|
|
{% for group in data %}{% for group_name, endpoints in group.items %}
|
|
<div class="NB-api-toc-header">{{ group_name }}</div>
|
|
<ul class="NB-api-toc">
|
|
{% for endpoint in endpoints %}
|
|
<li>
|
|
<div class="NB-api-link-desc">{{ endpoint.short_desc }}</div>
|
|
<a href="#{{ endpoint.url }}">{{ endpoint.method }} <code>{{ endpoint.url }}</code></a>
|
|
</li>
|
|
{% endfor %}
|
|
</ul>
|
|
{% endfor %}{% endfor %}
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
{% for group in data %}{% for group_name, endpoints in group.items %}
|
|
<div class="NB-module">
|
|
<h5 class="NB-module-title">{{ group_name }}</h5>
|
|
<div class="NB-module-content">
|
|
|
|
{% for endpoint in endpoints %}
|
|
<div class="NB-api-endpoint">
|
|
<h3><tt>{{ endpoint.method }} {{ endpoint.url }}</tt></h3>
|
|
<a class="NB-anchor" name="{{ endpoint.url }}"></a>
|
|
|
|
{% if endpoint.long_desc %}
|
|
<ul>
|
|
{% for desc in endpoint.long_desc %}
|
|
<li>{{ desc|safe }}</li>
|
|
{% endfor %}
|
|
</ul>
|
|
{% endif %}
|
|
|
|
{% if endpoint.params %}
|
|
<table>
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Description</th>
|
|
<th>Default</th>
|
|
<th>Example</th>
|
|
</tr>
|
|
{% for param in endpoint.params %}
|
|
<tr>
|
|
<td>{{ param.key }}</td>
|
|
<td class="NB-api-endpoint-param-desc">
|
|
{% if param.optional %}
|
|
<span class="optional">Optional</span>
|
|
{% else %}{% if param.required %}
|
|
<span class="required">Required</span>
|
|
{% endif %}{% endif %}
|
|
{{ param.desc|safe }}
|
|
</td>
|
|
<td>{% if param.default %}<code>{{ param.default }}</code>{% endif %}</td>
|
|
<td>{% if param.example %}<code>{{ param.example|safe }}</code>{% endif %}</td>
|
|
</tr>
|
|
{% endfor %}
|
|
</table>
|
|
{% endif %}
|
|
|
|
|
|
{# <h4>Example Response</h4> #}
|
|
{# <pre><code> #}
|
|
{# { #}
|
|
{# 'feeds': [] #}
|
|
{# } #}
|
|
{# </code></pre> #}
|
|
|
|
{% if endpoint.tips %}
|
|
<h4>Tips</h4>
|
|
<ul>
|
|
{% for tip in endpoint.tips %}
|
|
<li>{{ tip|safe }}</li>
|
|
{% endfor %}
|
|
</ul>
|
|
{% endif %}
|
|
</div>
|
|
{% endfor %}
|
|
</div>
|
|
</div>
|
|
{% endfor %}{% endfor %}
|
|
|
|
{# ===================== #}
|
|
{# = Terms of Services = #}
|
|
{# ===================== #}
|
|
|
|
|
|
<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>
|
|
|
|
{% endblock content %}
|
|
|
|
{% block footer %}
|
|
{% render_footer "api" %}
|
|
{% endblock footer %}
|