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>logo_format</strong>: If inline_logo is set to 1, the inlined image is converted to the specified format (either <em>png</em> or <em>jpeg</em>). If this option is not used, the original format is preserved.</li>
  34     <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>
  35     <li><strong>use_cache</strong>: Feeds are cached by the service according to the feed's caching headers. If use_cache is set to 1 (default) feeds are retrieved from the cache if possible. If set to 0, feeds are always fetched from their URL. Do not use 0 as a default value in your application.</li>
  36    </ul>
  37   </p>
  38   <p>Headers to /parse
  39    <ul>
  40     <li><a href="if-mod-since"></a><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>
  41     <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>
  42     <li><a name="accept"></a><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>
  43     <li><a name="accept-encoding"></a><strong>Accept-Encoding</strong>: Google App Engine gzips responses based on <em>Accept-Encoding</em> and <em>User-Agent</em> (<a href="http://code.google.com/appengine/docs/python/runtime.html#Responses">see documentation</a>). Include "gzip" in both headers to ensure gzip compression.</li>
  44    </ul>
  45   </p>
  46
  47   <h3>Responses</h3>
  48   <ul>
  49    <li>Each response contains a list of feeds, at least one for each <em>url</em>-Parameter</li>
  50    <li>HTTP-Redirects are followed automatically (this is reflected in the <em>urls</em> field)</li>
  51    <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>
  52    <li>Each feed contains
  53     <ul>
  54      <li><strong>title</strong>: the title of the feed</li>
  55      <li><strong>link</strong>: the feeds website</li>
  56      <li><strong>description</strong>: a description of the feed, potentially including HTML characters</li>
  57      <li><strong>author</strong>: the feed's author</li>
  58      <li><strong>language</strong>: the feed's language</li>
  59      <li><a name="urls" /><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>
  60      <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>
  61      <li><a name="logo" /><strong>logo</strong>: the URL of the feed's logo</li>
  62      <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>
  63      <li><strong>content_types</strong>: the content types of the feed, either audio, video or image</li>
  64      <li><strong>hub</strong>: the endpoint URL of the <a href="http://code.google.com/p/pubsubhubbub/">hub</a> through which the feed is published</li>
  65      <li><strong>errors</strong>: a dictionary of occured errors, where the key contains an <a href="#error-codes">error code</a> and the value a string representation.</li>
  66      <li><strong>episodes</strong>: the list of episodes</li>
  67     </ul>
  68    </li>
  69    <li>Each episode contains
  70     <ul>
  71      <li><strong>guid</strong>: an unique endentifier for the episode (provided by the feed in the GUID property)</li>
  72      <li><strong>title</strong>: the title of the episode</li>
  73      <li><strong>short_title</strong>: the non-repetitive part of the episode title. If an episode number is found, it is also removed and provided separately.</li>
  74      <li><strong>number</strong>: the episode number which is parsed from the title</li>
  75      <li><strong>description</strong>: the description of the episode, potentially including HTML characters</li>
  76      <li><strong>link</strong>: the website link for the episode</li>
  77      <li><strong>released</strong>: the timestamp of the episode's release in ISO 8601 (%Y-%m-%dT%H:%M:%S)</li>
  78      <li><strong>author</strong>: the episode's author</li>
  79      <li><strong>duration</strong>: the episode's duration in seconds</li>
  80      <li><strong>language</strong>: the episode's language</li>
  81      <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>
  82     </ul>
  83    </li>
  84    <li><a name="error-codes" />Current Error Codes
  85     <ul>
  86      <li><strong>fetch-feed</strong>: The feed could not be retrieved. The URL is given in the <a href="#urls">urls</a> list</li>
  87      <li><strong>fetch-logo</strong>: The feed's logo could not be retrieved. Its URL is given in the <a href="#logo">logo</a> field</li>
  88      <li><strong>hub-subscription</strong>: An error occured while subscribing to the feed's hub for instant updates. This is generally not critical for the client</li>
  89     </ul>
  90    </li>
  91   </ul>
  92   <p>Headers
  93    <ul>
  94     <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>
  95     <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>
  96     <li><strong>Content-Encoding</strong>: <em>gzip</em> if the response is compressed. See <em><a href="#accept-encoding">Accept-Encoding</a></em> for details.</li>
  97     <li><strong>Vary</strong>: Contains the request headers for which the response can vary. Currently this is <em>Accept, User-Agent, Accept-Encoding</em>.</li>
  98    </ul>
  99   </p>
 100
 101   <h3>Using this Instance</h3>
 102
 103   <p>If you intend to use <em>this instance</em> of the webservice in your
 104   application, please contact <a
 105   href="mailto:stefan@skoegl.net">stefan@skoegl.net</a> beforehand.
 106
 107   <h2>Source Code</h2>
 108   <p>The sourcecode is available from <a
 109   href="http://repo.or.cz/w/mygpo-feedservice.git">http://repo.or.cz/w/mygpo-feedservice.git</a>
 110   under the terms of the AGPLv3. Please report bugs on the <a href="https://bugs.gpodder.org/enter_bug.cgi?product=mygpo-feedservice">bugtracker</a> and mention the exact URL of your failed request.</p>
 111
 112
 113  </body>
 114 </html>