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   <link href="static/screen.css" type="text/css" rel="stylesheet" />
   5   <link href="static/prettify.css" type="text/css" rel="stylesheet" />
   6   <script type="text/javascript" src="static/prettify.js"></script>
   7   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   8   <title>gpodder.net Feed-Service</title>
   9  </head>
  10
  11  <body>
  12   <h1>gpodder.net Feed-Service</h1>
  13
  14   <p>The gpodder.net Feed-Service is a webservice for parsing podcast feeds and
  15   returning the simplified contents as JSON.</p>
  16
  17   <h2>Usage</h2>
  18
  19   <h3>Examples</h3>
  20   <pre class="prettyprint">
  21    SERVER=http://mygpo-feedservice.appspot.com/parse
  22    curl --header "Accept: application/json" "$SERVER?<strong>url</strong>=http://feeds.feedburner.com/linuxoutlaws&amp;<strong>inline_logo</strong>=1&amp;<strong>scale_logo</strong>=30" #<a href="/parse?url=http://feeds.feedburner.com/linuxoutlaws&inline_logo=1&scale_logo=30" title="see HTML response">^</a>
  23    curl --header "Accept: application/json" "$SERVER?<strong>url</strong>=http://leo.am/podcasts/floss&amp;<strong>url</strong>=http://feeds.twit.tv/floss_video_large"</a> #<a href="/parse?url=http://leo.am/podcasts/floss&url=http://feeds.twit.tv/floss_video_large" title="see HTML response">^</a>
  24    curl --header "Accept: application/json" "$SERVER?<strong>url</strong>=http://www.dancarlin.com/cswdc.xml&amp;<strong>strip_html</strong>=1"</a> #<a href="/parse?url=http://www.dancarlin.com/cswdc.xml?strip_html=1" title="see HTML response">^</a>
  25    curl --header "Accept: application/json" -d "url=http://feeds.feedburner.com/linuxoutlaws" $SERVER #<a href="/parse?url=http://feeds.feedburner.com/linuxoutlaws" title="see HTML response">^</a></pre>
  26
  27   <h3>Requests</h3>
  28   <p>Parameters to /parse (either GET or POST as application/x-www-form-urlencoded)
  29    <ul>
  30     <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>
  31     <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>
  32     <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>
  33     <li><strong>strip_html</strong>: If set to 1, all HTML tags are removed from text fields. If your client is not able to display HTML, use this option to reduce bandwidth usage.</li>
  34    </ul>
  35   </p>
  36   <p>Headers to /parse
  37    <ul>
  38     <li><a href="if-mod-since" /><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>
  39     <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>
  40     <li><a name="accept" /><strong>Accept</strong>: Clients should send <em>Accept: application/json</em> to indicate that they are prepared to receive JSON data. If you send a different Accept header, you will receive a HTML formatted response.</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. To save bandwidth, the logo is not included if it changed since the date sent in <em><a href="#if-mod-since">If-Modified-Since</a></em></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   <p>Headers
  78    <ul>
  79     <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. This header is not sent for the HTML formatted response.</li>
  80     <li><strong>Content-Type</strong>: <em>application/json</em> if your request contains <em>Accept: application/json</em>, otherwise the response will contain the HTML representation with <em>text/html</em>.</li>
  81    </ul>
  82   </p>
  83
  84   <h3>Using this Instance</h3>
  85
  86   <p>If you intend to use <em>this instance</em> of the webservice in your
  87   application, please contact <a
  88   href="mailto:stefan@skoegl.net">stefan@skoegl.net</a> beforehand.
  89
  90   <h2>Source Code</h2>
  91   <p>The sourcecode is available from <a
  92   href="http://repo.or.cz/w/mygpo-feedservice.git">http://repo.or.cz/w/mygpo-feedservice.git</a>
  93   under the terms of the AGPLv3.</p>
  94
  95
  96  </body>
  97 </html>