feedservice/index.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3  <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>gpodder.net Feed-Service</title>
   6
   7   <style>
   8 body {
   9     font-family: sans-serif;
  10 }
  11
  12 a, a:visited {
  13     color: black;
  14 }
  15
  16   </style>
  17  </head>
  18
  19  <body>
  20   <h1>gpodder.net Feed-Service</h1>
  21
  22   <p>The gpodder.net Feed-Service is a webservice for parsing podcast feeds and
  23   returning the simplified contents as JSON.</p>
  24
  25   <h2>Usage</h2>
  26
  27   <h3>Examples</h3>
  28   <pre>
  29    <a href="/parse?url=http://feeds.feedburner.com/linuxoutlaws&inline_logo=1&scale_logo=30">curl http://mygpo-feedservice.appspot.com/parse?<strong>url</strong>=http://feeds.feedburner.com/linuxoutlaws&<strong>inline_logo</strong>=1&<strong>scale_logo</strong>=30</a>
  30    <a href="/parse?url=http://leo.am/podcasts/floss&url=http://feeds.twit.tv/floss_video_large">curl http://mygpo-feedservice.appspot.com/parse?<strong>url</strong>=http://leo.am/podcasts/floss&<strong>url</strong>=http://feeds.twit.tv/floss_video_large</a>
  31    <a href="/parse?url=http://www.dancarlin.com/cswdc.xml">curl http://mygpo-feedservice.appspot.com/parse?<strong>url</strong>=http://www.dancarlin.com/cswdc.xml</a>
  32    curl -d url=http://feeds.feedburner.com/linuxoutlaws http://mygpo-feedservice.appspot.com/parse
  33   </pre>
  34
  35   <h3>Requests</h3>
  36   <p>Parameters to /parse (either GET or POST as application/x-www-form-urlencoded)
  37    <ul>
  38     <li><strong>url</strong>: The URL of the feed that should be parsed (required). This parameter can be repeated multiple times. The values can be URL-encoded.</li>
  39     <li><strong>inline_logo</strong>: If set to 1, the (unscaled) logos are included in the response as <a href="http://en.wikipedia.org/wiki/Data_URI_scheme">data URIs</a> (default 0).</li>
  40     <li><strong>scale_logo</strong>: If inline_logo is set to 1, scales the included logo down to the given size. The resulting image is fitted into a square with the given side-length. If the given size is greater than the original size, the image won't be scaled at all.</li>
  41    </ul>
  42   </p>
  43
  44   <h3>Responses</h3>
  45   <ul>
  46    <li>Each response contains a list of feeds, at least one for each <em>url</em>-Parameter</li>
  47    <li>HTTP-Redirects are followed automatically (this is reflected in the <em>urls</em> field)</li>
  48    <li><a href="http://cyber.law.harvard.edu/rss/rssRedirect.html">RSS-Redirects</a> are followed by additionally including the new feed in the response</li>
  49    <li>Each feed contains
  50     <ul>
  51      <li><strong>title</strong>: the title of the feed</li>
  52      <li><strong>link</strong>: the feeds website</li>
  53      <li><strong>description</strong>: a description of the feed, potentially including HTML characters</li>
  54      <li><strong>author</strong>: the feed's author</li>
  55      <li><strong>language</strong>: the feed's language</li>
  56      <li><strong>urls</strong>: the redirect-chain of the URL passed in the <em>url</em> parameter. This can be used to match the requested URLs to the entries in the response.</li>
  57      <li><strong>new_location</strong>: the referred to location, if the feed uses <a href="http://cyber.law.harvard.edu/rss/rssRedirect.html">RSS-Redirects</a>. The new location will also be included in the response</li>
  58      <li><strong>logo</strong>: the URL of the feed's logo</li>
  59      <li><strong>logo_data</strong>: the feed's logo as a <a href="http://en.wikipedia.org/wiki/Data_URI_scheme">data URI</a>, if <em>inline_logo</em> has been used</li>
  60      <li><strong>content_types</strong>: the content types of the feed, either audio, video or image</li>
  61      <li><strong>episodes</strong>: the list of episodes</li>
  62     </ul>
  63    </li>
  64    <li>Each episode contains
  65     <ul>
  66      <li><strong>title</strong>: the title of the episode</li>
  67      <li><strong>description</strong>: the description of the episode, potentially including HTML characters</li>
  68      <li><strong>link</strong>: the website link for the episode</li>
  69      <li><strong>timestamp</strong>: the timestamp of the episode's release in ISO 8601 (%Y-%m-%dT%H:%M:%S)</li>
  70      <li><strong>author</strong>: the episode's author</li>
  71      <li><strong>duration</strong>: the episode's duration in seconds</li>
  72      <li><strong>language</strong>: the episode's language</li>
  73      <li><strong>files</strong>: a list of all files linked by the episode. Each files is represented by an object containing url, filesize (in Bytes) and mimetype.</li>
  74     </ul>
  75    </li>
  76   </ul>
  77
  78   <h3>Using this Instance</h3>
  79
  80   <p>If you intend to use <em>this instance</em> of the webservice in your
  81   application, please contact <a
  82   href="mailto:stefan@skoegl.net">stefan@skoegl.net</a> beforehand.
  83
  84   <h2>Source Code</h2>
  85   <p>The sourcecode is available from <a
  86   href="http://repo.or.cz/w/mygpo-feedservice.git">http://repo.or.cz/w/mygpo-feedservice.git</a>
  87   under the terms of the AGPLv3.</p>
  88
  89
  90  </body>
  91 </html>