doc/api/reference/general.rst

   1 General Information
   2 ===================
   3
   4 Protocol
   5 --------
   6
   7 The API is provided via https. Requests via http will redirect to the
   8 corresponding URL via https.
   9
  10 CORS
  11 ----
  12
  13 All endpoints send the `Access-Control-Allow-Origin: *
  14 <http://www.w3.org/TR/cors/>`_ header which `allows web application to access
  15 the API <http://enable-cors.org/>`_.
  16
  17
  18 Identifying Podcasts and Episodes
  19 ---------------------------------
  20
  21 Podcast is identified by its feed URL, episode is identified by its media URL.
  22
  23
  24 Date Format
  25 -----------
  26
  27 Date format: ISO 8601 / `RFC 3339 <http://tools.ietf.org/html/rfc3339>`_:
  28 ``YYYY-MM-DDTHH:MM:SSZ``
  29
  30
  31 .. _formats:
  32
  33 Formats
  34 -------
  35
  36 All data is exchanged as `JSON <http://tools.ietf.org/html/rfc4627>`_. All
  37 resources are represented as JSON objects, and requests are expected as also
  38 expected to contain JSON objects.
  39
  40
  41 JSONP Callbacks
  42 ^^^^^^^^^^^^^^^
  43
  44 You can pass a ``json=<function-name>`` parameter to any GET call to have
  45 the results wrapped in a JSON function. This is typically used when browsers
  46 want to embed content received from the API in web pages by getting around
  47 cross domain issues. The response includes the same data output as the regular
  48 API, plus the relevant HTTP Header information.
  49
  50
  51 .. _api-parametrization:
  52
  53 API Parametrization
  54 -------------------
  55
  56 Since 2.7
  57
  58 Clients should retrieve and process clientconfig.json (see :doc:`clientconfig`)
  59 before making requests to the webservice. If a client can not process the
  60 configuration, it can assume the default configuration given in the
  61 clientconfig.json documentation.
  62
  63
  64 .. _devices:
  65
  66 Devices
  67 -------
  68
  69 Devices are used throughout the API to identify a device / a client
  70 application. A device ID can be any string matching the regular expression
  71 ``[\w.-]+``. The client application MUST generate a string to be used as its
  72 device ID, and SHOULD ensure that it is unique within the user account. A good
  73 approach is to combine the application name and the name of the host it is
  74 running on.
  75
  76 If two applications share a device ID, this might cause subscriptions to be
  77 overwritten on the server side. While it is possible to retrieve a list of
  78 devices and their IDs from the server, this SHOULD NOT be used to let a user
  79 select an existing device ID.
  80
  81
  82 Formats
  83 -------
  84 Most of the resources are offered in several different formats
  85
  86 * `OPML <http://www.opml.org/>`_
  87 * JSON
  88 * `JSONP <http://en.wikipedia.org/wiki/JSONP>`_ with an option function name
  89   that wraps the result (since 2.8)
  90 * plain text with one URL per line
  91 * XML a custom XML format (see `example <http://gpodder.net/toplist.xml>`_,
  92   since 2.9)
  93
  94
  95 JSON
  96 ^^^^
  97
  98 .. code-block:: json
  99
 100     [
 101      {
 102        "website": "http://sixgun.org",
 103        "description": "The hardest-hitting Linux podcast around",
 104        "title": "Linux Outlaws",
 105        "url": "http://feeds.feedburner.com/linuxoutlaws",
 106        "position_last_week": 1,
 107        "subscribers_last_week": 1943,
 108        "subscribers": 1954,
 109        "mygpo_link": "http://gpodder.net/podcast/11092",
 110        "logo_url": "http://sixgun.org/files/linuxoutlaws.jpg",
 111        "scaled_logo_url": "http://gpodder.net/logo/64/fa9fd87a4f9e488096e52839450afe0b120684b4.jpg"
 112      },
 113     ]
 114
 115
 116 XML
 117 ^^^
 118
 119 .. code-block:: xml
 120
 121     <podcasts>
 122      <podcast>
 123       <title>Linux Outlaws</title>
 124       <url>http://feeds.feedburner.com/linuxoutlaws</url>
 125       <website>http://sixgun.org</website>
 126       <mygpo_link>http://gpodder.net/podcast/11092</mygpo_link>
 127       <description>The hardest-hitting Linux podcast around</description>
 128       <subscribers>1954</subscribers>
 129       <subscribers_last_week>1943</subscribers_last_week>
 130       <logo_url>http://sixgun.org/files/linuxoutlaws.jpg</logo_url>
 131       <scaled_logo_url>http://gpodder.net/logo/64/fa9fd87a4f9e488096e52839450afe0b120684b4.jpg</scaled_logo_url>
 132      </podcast>
 133     </podcasts>
 134
 135
 136 API Variants
 137 ------------
 138
 139 Simple API
 140 ^^^^^^^^^^
 141
 142 The Simple API provides a way to upload and download subscription lists in
 143 bulk. This allows developers of podcast-related applications to quickly
 144 integrate support for the web service, as the only
 145
 146 * Synchronization of episode status fields is not supported
 147 * This API uses more bandwith than the advanced API
 148 * The client can be stateless
 149 * The client can be low-powered - subscribe/unsubscribe events are calculated
 150   on the server-side
 151
 152
 153 Advanced API
 154 ^^^^^^^^^^^^
 155
 156 The Advanced API provides more flexibility and enhanced functionality for
 157 applications that want a tighter integration with the web service. A reference
 158 implementation will be provided as part of the gPodder source code (and gPodder
 159 will make use of that reference implementation).
 160
 161 * The client has to persist the synchronization state locally
 162 * Only changes to subscriptions are uploaded and downloaded
 163 * Synchronization of episode status fields is supported in this API
 164 * Only JSON is used as the data format to ease development
 165