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   <p>Headers to /parse
  44    <ul>
  45     <li><strong>If-Modified-Since</strong>: Time when all requested feeds have been accessed the last time. The response will only contain podcasts that have been modified in the meantime.</li>
  46     <li><strong>User-Agent</strong>: Clients should send a descriptive User-Agent string. In case of abuse of the service, misbehaving and/or generic user-agents might be blocked.</li>
  47    </ul>
  48   </p>
  49
  50   <h3>Responses</h3>
  51   <ul>
  52    <li>Each response contains a list of feeds, at least one for each <em>url</em>-Parameter</li>
  53    <li>HTTP-Redirects are followed automatically (this is reflected in the <em>urls</em> field)</li>
  54    <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>
  55    <li>Each feed contains
  56     <ul>
  57      <li><strong>title</strong>: the title of the feed</li>
  58      <li><strong>link</strong>: the feeds website</li>
  59      <li><strong>description</strong>: a description of the feed, potentially including HTML characters</li>
  60      <li><strong>author</strong>: the feed's author</li>
  61      <li><strong>language</strong>: the feed's language</li>
  62      <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>
  63      <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>
  64      <li><strong>logo</strong>: the URL of the feed's logo</li>
  65      <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>
  66      <li><strong>content_types</strong>: the content types of the feed, either audio, video or image</li>
  67      <li><strong>episodes</strong>: the list of episodes</li>
  68     </ul>
  69    </li>
  70    <li>Each episode contains
  71     <ul>
  72      <li><strong>title</strong>: the title of the episode</li>
  73      <li><strong>description</strong>: the description of the episode, potentially including HTML characters</li>
  74      <li><strong>link</strong>: the website link for the episode</li>
  75      <li><strong>timestamp</strong>: the timestamp of the episode's release in ISO 8601 (%Y-%m-%dT%H:%M:%S)</li>
  76      <li><strong>author</strong>: the episode's author</li>
  77      <li><strong>duration</strong>: the episode's duration in seconds</li>
  78      <li><strong>language</strong>: the episode's language</li>
  79      <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>
  80     </ul>
  81    </li>
  82   </ul>
  83   <p>Headers
  84    <ul>
  85     <li><strong>Last-Modified</strong>: The timestamp of the latest change to any of the requested feeds. This value can be used in the If-Modified-Since parameter to subsequent requests.</li>
  86    </ul>
  87   </p>
  88
  89   <h3>Using this Instance</h3>
  90
  91   <p>If you intend to use <em>this instance</em> of the webservice in your
  92   application, please contact <a
  93   href="mailto:stefan@skoegl.net">stefan@skoegl.net</a> beforehand.
  94
  95   <h2>Source Code</h2>
  96   <p>The sourcecode is available from <a
  97   href="http://repo.or.cz/w/mygpo-feedservice.git">http://repo.or.cz/w/mygpo-feedservice.git</a>
  98   under the terms of the AGPLv3.</p>
  99
 100
 101  </body>
 102 </html>