doc/api/reference/events.rst

   1 Episode Actions API
   2 ===================
   3
   4 The episode actions API is used to synchronize episode-related events between
   5 individual devices. Clients can send and store events on the webservice which
   6 makes it available to other clients. The following types of actions are
   7 currently accepted by the API: download, play, delete, new. Additional types
   8 can be requested on the Mailing List.
   9
  10 Example use cases
  11
  12 * Clients can send ``download`` and ``delete`` events so that other clients
  13   know where a file has already been downloaded.
  14 * Clients can send ``play`` events with ``position`` information so that other
  15   clients know where to start playback.
  16 * Clients can send ``new`` states to reset previous events. This state needs
  17   to be interpreted by receiving clients and does not delete any information
  18   on the webservice.
  19
  20
  21 .. _episode-action-types:
  22
  23 Episode Action Types
  24 --------------------
  25
  26 * download
  27 * delete
  28 * play
  29 * new
  30 * flattr
  31
  32
  33 .. _api-episode-actions-add:
  34
  35 Upload Episode Actions
  36 ----------------------
  37
  38 ..  http:post:: /api/2/episodes/(username).json
  39     :synopsis: Upload new episode actions
  40
  41     * Requires HTTP authentication
  42     * Since 2.0
  43
  44     Upload changed episode actions. As actions are saved on a per-user basis
  45     (not per-device), the API endpoint is the same for every device. For
  46     logging purposes, the client can send the device ID to the server, so it
  47     appears in the episode action log on the website.
  48
  49     **Example request**:
  50
  51     .. sourcecode:: http
  52
  53         POST /api/2/episodes/some-user.json
  54
  55         [
  56           {
  57            "podcast": "http://example.com/feed.rss",
  58            "episode": "http://example.com/files/s01e20.mp3",
  59            "device": "gpodder_abcdef123",
  60            "action": "download",
  61            "timestamp": "2009-12-12T09:00:00"
  62           },
  63           {
  64            "podcast": "http://example.org/podcast.php",
  65            "episode": "http://ftp.example.org/foo.ogg",
  66            "action": "play",
  67            "started": 15,
  68            "position": 120,
  69            "total":  500
  70           }
  71         ]
  72
  73     :<json podcast: The feed URL to the podcast feed the episode belongs to (required)
  74     :<json episode: The media URL of the episode (required)
  75     :<json device: The device ID on which the action has taken place (see :ref:`devices`)
  76     :<json action: One of: download, play, delete, new (required)
  77     :<json timestamp: A UTC timestamp when the action took place, in ISO 8601 format
  78     :<json started: Only valid for "play". the position (in seconds) at which the client started playback. Requires position and total to be set.
  79     :<json position: Only valid for "play". the position (in seconds) at which the client stopped playback
  80     :<json total: Only valid for "play". the total length of the file in seconds. Requires position and started to be set.
  81
  82     **Example response**:
  83
  84     The return value is a JSON dictionary containing the timestamp and a list
  85     of URLs that have been rewritten (sanitized, see bug:747 and bug:862) as a
  86     list of tuples with the key "update_urls". The client SHOULD parse this
  87     list and update the local subscription and episode list accordingly (the
  88     server only sanitizes the URL, so the semantic "content" should
  89     stay the same and therefore the client can simply update the URL
  90     value locally and use it for future updates. An example result with
  91     update_urls:
  92
  93     .. sourcecode:: http
  94
  95         HTTP/1.1 200 OK
  96
  97         {
  98             "timestamp": 1337,
  99             "update_urls": [
 100                 ["http://feeds2.feedburner.com/LinuxOutlaws?format=xml",
 101                  "http://feeds.feedburner.com/LinuxOutlaws"],
 102                 ["http://example.org/episode.mp3 ",
 103                  "http://example.org/episode.mp3"]
 104             ]
 105         }
 106
 107     URLs that are not allowed (currently all URLs that contain non-ASCII
 108     characters or don't start with either http or https) are rewritten to
 109     the empty string and are ignored by the Webservice.
 110
 111
 112 .. _api-episode-actions-get:
 113
 114 Get Episode Actions
 115 -------------------
 116
 117 ..  http:get:: /api/2/episodes/(username).json
 118     :synopsis: retrieve new episode actions
 119
 120     * Requires HTTP authentication
 121     * Since 2.0
 122
 123
 124     Timestamps: The result is a list of all episode actions that were uploaded
 125     since the timestamp given in the since parameter (regardless of the action
 126     timestamp itself). The timestamp SHOULD be the value returned by
 127     the previous episode retrieve request. If no since value is given, ALL
 128     episode actions for the given user are returned. Please note that this
 129     could be a potentially long list of episode actions, so clients SHOULD
 130     provide a since value whenever possible (e.g. when uploads have been taken
 131     place before).
 132
 133     **Example response**:
 134
 135     The format of the action list is the same as with the action upload
 136     request, but the format is a bit different so that the server can send the
 137     new timestamp (that the client SHOULD save and use for subsequent
 138     requests):
 139
 140     .. sourcecode:: http
 141
 142         HTTP/1.1 200 OK
 143
 144         {
 145             "actions": [],
 146             "timestamp": 12345
 147         }
 148
 149     Client implementation notes: A client can make use of the device variant of
 150     this request when it is assigned a single device id. When adding a podcast
 151     to the client (without synching the subscription list straight away), the
 152     variant with the podcast URL can be used. The first variant (no parameters
 153     at all) can be used as a kind of "burst" download of all episode
 154     actions, but should be used as little as possible (e.g. after a re-install,
 155     although even then, the device-id parameter could be more useful).
 156
 157     :query string podcast: The URL of a Podcast feed; if set, only actions for episodes of the given podcast are returned
 158     :query string device: A Device ID; if set, only actions for the given device are returned
 159     :query int since: Only episode actions since the given timestamp are returned
 160     :query bool aggregated: If true, only the latest actions is returned for each episode (added in 2.1)