/dev/api: Clarify the xml/rss api documentation

The xml extension in the api documentation is slightly misleading in
that it appears to indicate that we support an xml api. The .xml
extension is intended for rss consumption so we are replacing the
'extensions' with an rss support flag.

r2/r2/controllers/api.py

@@ -233,7 +233,7 @@ def GET_me(self, responder):
             return {}
 
     @json_validate(user=VUname(("user",)))
-    @api_doc(api_section.users, extensions=["json"])
+    @api_doc(api_section.users)
     def GET_username_available(self, responder, user):
         """
         Check whether a username is available for registration.
@@ -281,7 +281,7 @@ def POST_check_email(self, responder, email):
 
     @allow_oauth2_access
     @json_validate()
-    @api_doc(api_section.captcha, extensions=["json"])
+    @api_doc(api_section.captcha)
     def GET_needs_captcha(self, responder):
         """
         Check whether CAPTCHAs are needed for API methods that define the
@@ -344,7 +344,7 @@ def POST_compose(self, form, jquery, from_sr, to, subject, body):
 
     @require_oauth2_scope("submit")
     @json_validate()
-    @api_doc(api_section.subreddits, uses_site=True, extensions=["json"])
+    @api_doc(api_section.subreddits, uses_site=True)
     def GET_submit_text(self, responder):
         """Get the submission text for the subreddit.
 
@@ -2796,7 +2796,7 @@ def POST_distinguish(self, form, jquery, thing, how):
 
     @require_oauth2_scope("save")
     @json_validate(VUser())
-    @api_doc(api_section.links_and_comments, extensions=["json"])
+    @api_doc(api_section.links_and_comments)
     def GET_saved_categories(self, responder):
         """Get a list of categories in which things are currently saved.
 
@@ -3915,7 +3915,7 @@ def POST_tb_commentspanel_hide(self):
     @require_oauth2_scope("read")
     @json_validate(query=VPrintable('query', max_length=50),
                    include_over_18=VBoolean('include_over_18', default=True))
-    @api_doc(api_section.subreddits, extensions=["json"])
+    @api_doc(api_section.subreddits)
     def POST_search_reddit_names(self, responder, query, include_over_18):
         """List subreddit names that begin with a query string.
 
@@ -4037,7 +4037,7 @@ def POST_disable_otp(self, form, jquery):
 
     @require_oauth2_scope("read")
     @json_validate(query=VLength("query", max_length=50))
-    @api_doc(api_section.subreddits, extensions=["json"])
+    @api_doc(api_section.subreddits)
     def GET_subreddits_by_topic(self, responder, query):
         """Return a list of subreddits that are relevant to a search query."""
         if not g.CLOUDSEARCH_SEARCH_API:

r2/r2/controllers/api_docs.py

@@ -126,7 +126,7 @@ def docs_from_controller(controller, url_prefix='/api', oauth_only=False):
         - `doc`: Markdown-formatted docstring.
         - `uri`: Manually-specified URI to list the API method as
         - `uri_variants`: Alternate URIs to access the API method from
-        - `extensions`: URI extensions the API method supports
+        - `supports_rss`: Indicates the URI also supports rss consumption
         - `parameters`: Dictionary of possible parameter names and descriptions.
         - `extends`: API method from which to inherit documentation
         - `json_model`: The JSON model used instead of normal POST parameters
@@ -160,13 +160,11 @@ def docs_from_controller(controller, url_prefix='/api', oauth_only=False):
                         docs["doc"] = notes
 
                 uri = docs.get('uri') or '/'.join((url_prefix, action))
-                if 'extensions' in docs:
-                    # if only one extension was specified, add it to the URI.
-                    if len(docs['extensions']) == 1:
-                        uri += '.' + docs['extensions'][0]
-                        del docs['extensions']
                 docs['uri'] = uri
 
+                if 'supports_rss' not in docs:
+                    docs['supports_rss'] = False
+
                 if api_doc['uses_site']:
                     docs["in-subreddit"] = True
 

r2/r2/controllers/front.py

@@ -218,7 +218,7 @@ def POST_comments(self, article, comment, context, sort, limit, depth):
     @api_doc(api_section.listings,
              uri='/comments/{article}',
              uses_site=True,
-             extensions=['json', 'xml'])
+             supports_rss=True)
     def GET_comments(
         self, article, comment, context, sort, limit, depth,
         showedits=True, showmore=True):
@@ -475,7 +475,7 @@ def _make_moderationlog(self, srs, num, after, reverse, count, mod=None, action=
         action=VOneOf('type', ModAction.actions),
     )
     @api_doc(api_section.moderation, uses_site=True,
-             uri="/about/log", extensions=["json", "xml"])
+             uri="/about/log", supports_rss=True)
     def GET_moderationlog(self, num, after, reverse, count, mod, action):
         """Get a list of recent moderation actions.
 
@@ -748,8 +748,7 @@ def GET_flairlisting(self, num, after, reverse, count, name):
     @validate(location=nop('location'),
               created=VOneOf('created', ('true','false'),
                              default='false'))
-    @api_doc(api_section.subreddits, uri="/r/{subreddit}/about/edit",
-             extensions=["json"])
+    @api_doc(api_section.subreddits, uri="/r/{subreddit}/about/edit")
     def GET_editreddit(self, location, created):
         """Get the current settings of a subreddit.
 
@@ -765,7 +764,7 @@ def GET_editreddit(self, location, created):
             return self._edit_normal_reddit(location, created)
 
     @require_oauth2_scope("read")
-    @api_doc(api_section.subreddits, uri='/r/{subreddit}/about', extensions=['json'])
+    @api_doc(api_section.subreddits, uri='/r/{subreddit}/about')
     def GET_about(self):
         """Return information about the subreddit.
 
@@ -841,7 +840,7 @@ def GET_related(self, num, article, after, reverse, count):
     @api_doc(
         api_section.listings,
         uri="/duplicates/{article}",
-        extensions=['json', 'xml'],
+        supports_rss=True,
     )
     def GET_duplicates(self, article, num, after, reverse, count):
         """Return a list of other submissions of the same URL"""
@@ -869,7 +868,7 @@ def GET_duplicates(self, article, num, after, reverse, count):
     @base_listing
     @require_oauth2_scope("read")
     @validate(query=nop('q', docs={"q": "a search query"}))
-    @api_doc(api_section.subreddits, uri='/subreddits/search', extensions=['json', 'xml'])
+    @api_doc(api_section.subreddits, uri='/subreddits/search', supports_rss=True)
     def GET_search_reddits(self, query, reverse, after, count, num):
         """Search subreddits by title and description."""
         q = SubredditSearchQuery(query)
@@ -896,7 +895,7 @@ def GET_search_reddits(self, query, reverse, after, count, num):
               recent=VMenu('t', TimeMenu, remember=False),
               restrict_sr=VBoolean('restrict_sr', default=False),
               syntax=VOneOf('syntax', options=SearchQuery.known_syntaxes))
-    @api_doc(api_section.search, extensions=['json', 'xml'], uses_site=True)
+    @api_doc(api_section.search, supports_rss=True, uses_site=True)
     def GET_search(self, query, num, reverse, after, count, sort, recent,
                    restrict_sr, syntax):
         """Search links page."""

r2/r2/controllers/listingcontroller.py

@@ -236,7 +236,7 @@ def GET_listing(self, **env):
     section=api_section.listings,
     extends=ListingController.GET_listing,
     notes=[paginated_listing.doc_note],
-    extensions=["json", "xml"],
+    supports_rss=True,
 )
 
 
@@ -892,8 +892,7 @@ def GET_listing(self, where, vuser, sort, time, show, **env):
 
     @require_oauth2_scope("read")
     @validate(vuser = VExistingUname('username'))
-    @api_doc(section=api_section.users, uri='/user/{username}/about',
-             extensions=['json'])
+    @api_doc(section=api_section.users, uri='/user/{username}/about')
     def GET_about(self, vuser):
         """Return information about the user, including karma and gold status."""
         if (not is_api() or

r2/r2/public/static/css/reddit.less

@@ -8617,18 +8617,25 @@ div.usertable .note {
 
 .api-help .oauth-scope-list { display: inline; margin-left: 1em; }
 
-.api-help .oauth-scope {
+.api-help .api-badge {
     display: inline-block;
     margin-left: 0.5em;
-    font-size: .75em; 
+    font-size: .75em;
     font-weight: normal;
     vertical-align: bottom;
-    background: #577439;
     color: #fbfbf9;
     padding: 2px 6px;
     border-radius: 2px;
 }
 
+.api-badge.oauth-scope {
+    background: #577439;
+}
+
+.api-badge.rss-support {
+    background: #f38f35;
+}
+
 .api-help .overview h2,
 .api-help .methods h2 {
     color: black;

r2/r2/templates/apihelp.html

@@ -229,18 +229,20 @@ <h3 id="fullnames">fullnames</h3>
             <h3>
               <span class="method">${method}&nbsp;</span>
               ${api_uri_with_sr_maybe(uri, in_subreddit)}
-              %if 'extensions' in docs:
-                <span class="extensions">
-                  [ ${' | '.join('.'+extension for extension in docs['extensions'])} ]
-                </span>
-              %endif
               %if docs['oauth_scopes']:
                 <span class="oauth-scope-list">
                   %for scope in docs['oauth_scopes']:
-                    <span class="oauth-scope">${scope or "any"}</span>
+                    <a href="https://github.com/reddit/reddit/wiki/OAuth2">
+                        <span class="api-badge oauth-scope">${scope or "any"}</span>
+                    </a>
                   %endfor
                 </span>
               %endif
+              %if docs['supports_rss']:
+                <a href="https://www.reddit.com/wiki/rss">
+                    <span class="api-badge rss-support">rss support</span>
+                </a>
+              %endif
             </h3>
             %if 'uri_variants' in docs:
               <ul class="uri-variants">