doc/api/reference/events.rst

   1 .. _events-api:
   2
   3 Events API
   4 ==========
   5
   6 The **Events API** can be used by clients to exchange information about the
   7 status of podcast episodes. Clients upload events with certain actions such as
   8 *play* to inform other clients that an episode has already been played. Clients
   9 can receive episode actions, for example on startup, to update the status of
  10 episodes accordingly.
  11
  12
  13 Resources
  14 ---------
  15
  16 The Events API defines the following resources ::
  17
  18     /user/<username>/events
  19     /user/<username>/events/response/<id>
  20     /user/<username>/events/device/<device-id>
  21
  22
  23 Event Data
  24 ----------
  25
  26 An event is a JSON object with the following attributes.
  27
  28 +--------------+----------+---------------------------------------------------+
  29 | Attribute    | Required | Values                                            |
  30 +==============+==========+===================================================+
  31 | action       | yes      | one of ``play``, ``download``, ``flattr``,        |
  32 |              |          | ``delete``                                        |
  33 +--------------+----------+---------------------------------------------------+
  34 | timestamp    | yes      | The UTC timestamp at which the event occured as   |
  35 |              |          | `RFC 3339 <http://www.ietf.org/rfc/rfc3339.txt>`_ |
  36 +--------------+----------+---------------------------------------------------+
  37 | podcast      | yes      | The feed URL of the podcast                       |
  38 +--------------+----------+---------------------------------------------------+
  39 | episode      | yes      | The media URL of the episode                      |
  40 +--------------+----------+---------------------------------------------------+
  41 | device       | no       | The device ID at which the event was triggered    |
  42 +--------------+----------+---------------------------------------------------+
  43 | started      | no       | The position (in seconds) at which a play event   |
  44 |              |          | started                                           |
  45 +--------------+----------+---------------------------------------------------+
  46 | positon      | no       | The position (in seconds) at which a play event   |
  47 |              |          | was stopped                                       |
  48 +--------------+----------+---------------------------------------------------+
  49 | total        | no       | The total duratin (in seconds) of the media file  |
  50 +--------------+----------+---------------------------------------------------+
  51
  52
  53 Event Types
  54 ^^^^^^^^^^^
  55
  56 The following types of events (*actions*) are currently defined.
  57
  58 * *play*: the episode has been played
  59 * *download*: the episode has been downloaded
  60 * *flattr*: the episode has been flattered
  61 * *delete*: the episode has been deleted
  62
  63 Additional event types might be defined in the future. To ensure forward
  64 compatability, clients should accept (in if necessary ignore) events of unknown
  65 type.
  66
  67
  68 Upload Events
  69 -------------
  70
  71 Clients can upload new events to gpodder.net to make them available online and
  72 for other clients. Clients MUST NOT upload events that have not been triggered
  73 through them (ie events that have been donwloaded from the API).
  74
  75 Clients SHOULD aggregate events in upload them in batches.
  76
  77
  78 Request
  79 ^^^^^^^
  80
  81 To initiate an upload, the following request should be issued. ::
  82
  83     POST /user/<username>/events
  84     Content-Tpe: application/json
  85
  86     {
  87         events: [
  88             { event },
  89             { event },
  90             ...
  91         ]
  92     }
  93
  94 Clients MUST NOT upload an empty list of events.
  95
  96 TODO: add ``default_data`` attribute to object, to avoid repeating the same
  97 data over and over?
  98
  99 Clients MUST NOT upload invalid event objects.
 100
 101 If events reference devices that do not yet exist, they are automatically
 102 created with default data.
 103
 104 TODO: specify device-id at top-level? what about events that don't belong to
 105 any device? move device-id to URL?
 106
 107
 108 Response
 109 ^^^^^^^^
 110
 111 The following responses are possible.
 112
 113 The uploaded list of events has been processed immediatelly ::
 114
 115     204 No Content
 116
 117
 118 The uploaded list of events has been accepted for later processing ::
 119
 120     202 Accepted
 121
 122
 123 TODO: Validation?
 124
 125
 126 Data
 127 ^^^^
 128
 129 No payload data is returned as a response to uploading events.
 130
 131
 132 Download Events
 133 ---------------
 134
 135 Clients can download events to retrieve those that have been uploaded by other
 136 devices (or itself) since a certain timestamp.
 137
 138 It is RECOMMENDED that clients do not persistently store events after they have
 139 been uploaded. Instead they SHOULD download events after an upload, to retrieve
 140 all events that they (and other clients) have uploaded.
 141
 142
 143 Requests
 144 ^^^^^^^^
 145
 146 Download requests retrieve events that have been uploaded since a specific
 147 timestamp. This timestamp can be given explicitly (if the corresponding
 148 timestamp value is maintained) is implicitly by the device-id (the
 149 server maintains a timestamp per device).
 150
 151 **Explicit Timestamp:** retrieve all events after a specific timestamp. ::
 152
 153     GET /user/<username>/events?since=<timestamp>
 154
 155 Parameters
 156
 157 * since: numeric timestamp value (mandatory)
 158
 159
 160 **Implicit Timestamp:** retrieve all events that the current device has not yet
 161 seen. The timestamp of is stored on the server side. ::
 162
 163     GET /user/<username>/device/<device-id>/events
 164
 165 Parameters
 166
 167 * reset: can be set to true to reset the server-side timestamp to 0 and
 168   retrieve all events.
 169
 170
 171 Responses
 172 ^^^^^^^^^
 173
 174 Response ::
 175
 176     200 OK
 177     Content-Tpe: application/json
 178     TODO ...?
 179
 180     {
 181         since: ...,
 182         timestamp: ...,
 183         events: [
 184             { event },
 185             { event },
 186             ...
 187         ]
 188     }
 189
 190
 191 Response is being prepared ::
 192
 193     203 Found / 202 See Other
 194     Link: /user/<username>/events/response/<id>
 195
 196
 197 The server is preparing the result at the specified resource. The client should
 198 try to fetch the data from the given URLs. ::
 199
 200     GET /user/<username>/events/<id>
 201     Content-Tpe: application/json
 202
 203
 204 A 404 might be returned before the data is ready. The client may retry after
 205 xxx seconds. ::
 206
 207     404 Not Found
 208
 209
 210 When the data is ready, 200 will be returned ::
 211
 212     200 OK
 213     Content-Tpe: application/json
 214
 215     TODO: body...
 216
 217
 218 When the data is no longer available, a 410 is returned. ::
 219
 220     410 Gone
 221
 222 In this case the client SHOULD retry with the previous ``since`` value.
 223
 224 A successful response indicates a timeframe (between ``since`` and
 225 ``timestamp``) for which events have been retrieved. When using
 226 *explicit* queries, the client MUST use the value of the last respone's
 227 ``timestamp`` field as the value of the ``since`` parameter in the following
 228 request. The ``since`` paramter can be set to ``0`` if previously retrieved
 229 events have been lost (eg through a database reset). This MUST, however, be an
 230 exceptional case.
 231
 232
 233 Data
 234 ^^^^
 235
 236 The client can expect the retrieved events to be well-formed but SHOULD be able
 237 to at least safely ignore invalid events. This includes events with an
 238 ``action`` which is not listed above. While the API does perform input
 239 validation on uploaded events, this should ensure that clients are able to
 240 remain operational if for example new event types are introduced which have
 241 different requirements to the provided attributes.