From d1fd28b702304b98e8f7ed16dfa80e0ce23027a7 Mon Sep 17 00:00:00 2001 From: Samuel Clay Date: Sat, 23 Apr 2011 23:15:44 -0400 Subject: [PATCH] Adding the last few endpoints. Now just need to write out descriptions and params for all of them and we're done. --- apps/static/views.py | 9 +- media/css/reader.css | 19 +- templates/static/api.xhtml | 458 ++++++-------------------------- templates/static/api.yml | 65 ++++- templates/static/api_yaml.xhtml | 148 ----------- 5 files changed, 150 insertions(+), 549 deletions(-) delete mode 100644 templates/static/api_yaml.xhtml diff --git a/apps/static/views.py b/apps/static/views.py index 8f3bf76e2..cb14b3f3a 100644 --- a/apps/static/views.py +++ b/apps/static/views.py @@ -15,14 +15,15 @@ def about(request): context_instance=RequestContext(request)) def faq(request): - return render_to_response('static/api.xhtml', {}, + return render_to_response('static/faq.xhtml', {}, context_instance=RequestContext(request)) def api(request): - filename = settings.TEMPLATE_DIRS[0] + '/static/api.yml' + filename = settings.TEMPLATE_DIRS[0] + '/static/api.yml' api_yml_file = open(filename).read() - data = yaml.load(api_yml_file) - return render_to_response('static/api_yaml.xhtml', { + data = yaml.load(api_yml_file) + + return render_to_response('static/api.xhtml', { 'data': data }, context_instance=RequestContext(request)) diff --git a/media/css/reader.css b/media/css/reader.css index a32926169..b11053013 100644 --- a/media/css/reader.css +++ b/media/css/reader.css @@ -5223,6 +5223,9 @@ background: transparent; .NB-static-api h3 { /* margin-top: 64px;*/ } +.NB-static-api h4 { + margin-top: 12px; +} .NB-static-api .NB-api-endpoint { /* margin-left: 12px;*/ /* padding-left: 18px;*/ @@ -5250,21 +5253,23 @@ background: transparent; margin: 12px 0; } .NB-static-api table { - width: 620px; + width: 600px; border-spacing: 0 0; - margin: 24px 0; -/* border: 1px solid #B0B0B0;*/ + margin: 24px 0 12px 20px; + background: transparent url('../img/reader/static_bullet_white.png') no-repeat 0 0; + border-bottom: 1px solid #F6F6F6; } .NB-static-api table th, .NB-static-api table td { text-align: left; vertical-align: top; - padding: 7px 20px 7px 10px; + padding: 7px 8px 7px 8px; margin: 0; } .NB-static-api table td { border-right: 1px solid #F6F6f6; + white-space: nowrap; /* border-bottom: 1px solid #F6F6f6;*/ } .NB-static-api table td:last-child { @@ -5276,7 +5281,7 @@ background: transparent; background: -moz-linear-gradient(center bottom, #FCFCFC 0%, #E0E0E0 100%); border-right: 1px solid #BBB; border-bottom: 1px solid #BBB; - padding: 2px 20px 2px 10px; + padding: 2px 8px; color: #222; font-size: 10px; text-transform: uppercase; @@ -5316,4 +5321,8 @@ background: transparent; font-size: 12px; line-height: 16px; margin-bottom: 12px; +} +.NB-static-api .NB-api-endpoint-param-desc { + width: 100%; + white-space: normal; } \ No newline at end of file diff --git a/templates/static/api.xhtml b/templates/static/api.xhtml index db8aef685..9dd38111d 100644 --- a/templates/static/api.xhtml +++ b/templates/static/api.xhtml @@ -24,7 +24,7 @@ /reader/ views, /rss_feeds/ views, as well as - this page itself.

+ the API definitions in YML.

@@ -37,397 +37,87 @@
-
Feeds
- - -
Stories
- - -
Feed Management
- - -
Import/Export
- + {% for group in data %}{% for group_name, endpoints in group.items %} +
{{ group_name }}
+ + {% endfor %}{% endfor %}
- -
-
Feeds
-
+ + + {% for group in data %}{% for group_name, endpoints in group.items %} +
+
{{ group_name }}
+
-
-

GET /reader/feeds

- + {% for endpoint in endpoints %} +
+

{{ endpoint.method }} {{ endpoint.url }}

+ -
    -
  • Retrieve a user's list of feeds. Includes the 3 unread counts (positive, neutral, - negative), as well as optional favicons.
    • -
+ {% if endpoint.long_desc %} +
    + {% for desc in endpoint.long_desc %} +
  • {{ desc|safe }}
    • + {% endfor %} +
+ {% endif %} - - - - - - - - - - - - - - - - - - - -
ParameterDescriptionDefaultExample
include_faviconsOptional Include - favicons inline. Since they can be time consuming to download, you can optionally - turn them off. Use /api/v1/feeds/favicons/ to retrieve the favicons in a - separate request.truetrue/false
flatOptional Returns a flat folder structure instead of nested folders. Useful when displaying all folders in a single depth without recursive descent.falsetrue/false
- -

Example Response

- - 

-  {
-    'feeds': []
-  }
-
- -

Tips

- -
    -
  • Use /reader/refresh_feeds to get updated unread counts.
    • -
  • Turn off include_favicons if you can either cache favicons or can - wait to fetch them.
    • -
+ {% if endpoint.params %} + + + + + + + + {% for param in endpoint.params %} + + + + + + + {% endfor %} +
ParameterDescriptionDefaultExample
{{ param.key }} + {% if param.optional %} + Optional + {% else %}{% if param.required %} + Required + {% endif %}{% endif %} + {{ param.desc|safe }} + {% if param.default %}{{ param.default }}{% endif %}{{ param.example }}
+ {% endif %} + + +{#

Example Response

#} +{# 
 #}
+{# { #}
+{#   'feeds': [] #}
+{# } #}
+{#
#} + + {% if endpoint.tips %} +

Tips

+
    + {% for tip in endpoint.tips %} +
  • {{ tip|safe }}
    • + {% endfor %} +
+ {% endif %} +
+ {% endfor %}
- - -
-

GET /reader/favicons

- - -
    -
  • Retrieve a list of favicons for a list of feeds. Used when combined with - /reader/feeds and include_favicons=false, so the - feeds request contains far less data. Useful for mobile devices, but requires a - second request.
    • -
- - - - - - - - - - - - - - -
ParameterDescriptionDefaultExample
feedsOPTIONAL Array of feed ids. Leave empty to retrieve all active (enabled) feeds.[1, 2, 3]
- -

Example Response

- - 

-  {
-    'feeds': []
-  }
-
- -

Tips

- -
    -
  • To use inline data images, you can use this syntax: - 
    
-  <img src="data:image/png;base64,[IMAGE_DATA_STRING]" />
-
    -
    • -
-
- - -
-

GET /reader/page/:id

- - -
    -
  • Retrieve the original page from a single feed.
    • -
- -

Example Response

- - 

-  {#  #}
-  {#  #}
-  {#    #}
-  {#   Proxied Page #}
-  {#  #}
-  {#  #}
-  {#   
This is a proxied page. This is straight HTML.
 #}
-  {#  #}
-  {#  #}
-
-
- - -
-

GET /reader/refresh_feeds

- - -
    -
  • Up-to-the-second unread counts for each active feed.
    • -
  • Poll for these counts no more than once a minute.
    • -
- -

Example Response

- - 

-{
-  'feeds': []
-}
-
-
-
-
- - - {# =========== #} - {# = Stories = #} - {# =========== #} - - -
-
Stories
-
- - -
-

GET /reader/feed/:id

- - -
    -
  • Retrieve stories from a single feed.
    • -
- - - - - - - - - - - - - - -
ParameterDescriptionDefaultExample
pageoptional Page of stories, starting from 1.12
- -

Example Response

- - 

-  {
-    'feeds': []
-  }
-
-
- - -
-

GET /reader/starred_stories

- - -
    -
  • Retrieve a user's starred stories.
    • -
- - - - - - - - - - - - - - -
ParameterDescriptionDefaultExample
pageoptional Page of starred stories, starting from 1.12
- -

Example Response

- - 

-  {
-    'feeds': []
-  }
-
-
- - -
-

GET /reader/river_stories

- - -
    -
  • Retrieve stories from a collection of feeds. This is known as the River of News.
    • -
  • Stories are ordered in reverse chronological order.
    • -
- - - - - - - - - - - - - - - - - - - - -
ParameterDescriptionDefaultExample
feedsrequired List of feed ids.[12, 24, 36]
pageoptional Page of stories, starting from 1.12
- -

Example Response

- - 

-  {
-    'feeds': []
-  }
-
-
- -
-
- - - {# ================ #} - {# = Intelligence = #} - {# ================ #} - -
-
Intelligence
-
- -
-
- -
-
- + {% endfor %}{% endfor %} {# ===================== #} {# = Terms of Services = #} diff --git a/templates/static/api.yml b/templates/static/api.yml index 1a4ffb649..b4e98574f 100644 --- a/templates/static/api.yml +++ b/templates/static/api.yml @@ -94,14 +94,21 @@ method: 'GET' short_desc: "Stories from multiple feeds (River of News)." long_desc: - - "" - tips: - - '' + - "Retrieve stories from a collection of feeds. This is known as the River of News." + - "Stories are ordered in reverse chronological order." params: + - key: 'feeds' + desc: "Feed ids to use in the river. Usually every feed in a folder with unread stories." + required: true + example: "[12, 24, 36]" - key: 'page' desc: "Page of stories, starting from 1." optional: true example: "2" + - key: 'read_stories_count' + desc: "An optimization used to skip a set number of stories that are guaranteed to be read. Pass in the number of stories that have been read from this series. If your page >= 2, you should probably have some read stories from the first page." + optional: true + example: "12" - url: '/reader/mark_story_as_read' method: 'POST' @@ -261,12 +268,13 @@ example: "[1, 2, 3]" -- "import/export": - - url: '/import/opml_upload' - method: 'POST' - short_desc: "Upload OPML file." +- "intelligence classifiers": + - url: '/get/publisher' + method: 'GET' + short_desc: "Get the intelligence classifiers for a user's site." long_desc: - - "" + - "Get the intelligence classifiers for a user's site." + - "Includes both popular classifiers and the user's own classifiers." tips: - '' params: @@ -275,9 +283,50 @@ optional: true example: "[1, 2, 3]" + - url: '/save/publisher' + method: 'POST' + short_desc: "Save intelligence classifiers for a feed." + long_desc: + - "Save intelligence classifiers (tags, titles, authors, and the feed) for a feed." + tips: + - '' + params: + - key: '' + desc: "" + optional: true + example: "[1, 2, 3]" + + - url: '/save/story' + method: 'POST' + short_desc: "Save intelligence classifiers from a specific story." + long_desc: + - "Save intelligence classifiers (tags, titles, authors, and the feed) from a specific story." + tips: + - '' + params: + - key: '' + desc: "" + optional: true + example: "[1, 2, 3]" + + +- "import/export": - url: '/import/opml_export' method: 'GET' short_desc: "Download backup of feeds as an OPML file." + long_desc: + - "" + tips: + - '' + params: + - key: '' + desc: "" + optional: true + example: "[1, 2, 3]" + + - url: '/import/opml_upload' + method: 'POST' + short_desc: "Upload OPML file." long_desc: - "" tips: diff --git a/templates/static/api_yaml.xhtml b/templates/static/api_yaml.xhtml deleted file mode 100644 index e58b0ca1e..000000000 --- a/templates/static/api_yaml.xhtml +++ /dev/null @@ -1,148 +0,0 @@ -{% extends 'base.html' %} - -{% block bodyclass %}NB-static NB-static-api{% endblock %} - -{% block title %}The NewsBlur API{% endblock %} - -{% block content %} - -
- The NewsBlur API -
- - -
-
Introduction to the API
-
-

NewsBlur is an RSS feed reader with intelligence.

-

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.

-

It is a very nice thing to note that this entire API is open-source, including - the implementation of the endpoints. You can find the source of the - /reader/ views, - /rss_feeds/ views, - as well as - the API definitions in YML.

-
-
- - {# ========= #} - {# = Feeds = #} - {# ========= #} - -
-
API Table of Contents
- -
-
- {% for group in data %}{% for group_name, endpoints in group.items %} -
{{ group_name }}
- - {% endfor %}{% endfor %} -
-
-
- - - {% for group in data %}{% for group_name, endpoints in group.items %} -
-
{{ group_name }}
-
- - {% for endpoint in endpoints %} -
-

{{ endpoint.method }} {{ endpoint.url }}

- - - {% if endpoint.long_desc %} -
    - {% for desc in endpoint.long_desc %} -
  • {{ desc|safe }}
    • - {% endfor %} -
- {% endif %} - - {% if endpoint.params %} - - - - - - - - {% for param in endpoint.params %} - - - - - - - {% endfor %} -
ParameterDescriptionDefaultExample
{{ param.key }} - {% if param.optional %} - Optional - {% else %}{% if param.required %} - Required - {% endif %}{% endif %} - {{ param.desc|safe }} - {% if param.default %}{{ param.default }}{% endif %}{{ param.example }}
- {% endif %} - - -{#

Example Response

#} -{# 
 #}
-{# { #}
-{#   'feeds': [] #}
-{# } #}
-{#
#} - - {% if endpoint.tips %} -

Tips

-
    - {% for tip in endpoint.tips %} -
  • {{ tip|safe }}
    • - {% endfor %} -
- {% endif %} -
- {% endfor %} -
-
- {% endfor %}{% endfor %} - - {# ===================== #} - {# = Terms of Services = #} - {# ===================== #} - - -
-
API Guidelines and Terms of Service
-
-

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.

- -

If your project or application allows users to interact with data from NewsBlur, - you must cite NewsBlur as the source of your data.

- -

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.

- -

We reserve the right to revise these guidelines. If you violate the spirit of - these terms, expect to be blocked without advance warning.

-
-
- -{% endblock content %} \ No newline at end of file