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
16 The Events API defines the following resources ::
18 /user/<username>/events
19 /user/<username>/events/response/<id>
20 /user/<username>/events/device/<device-id>
26 An event is a JSON object with the following attributes.
28 +--------------+----------+---------------------------------------------------+
29 | Attribute | Required | Values |
30 +==============+==========+===================================================+
31 | action | yes | one of ``play``, ``download``, ``flattr``, |
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 |
45 +--------------+----------+---------------------------------------------------+
46 | positon | no | The position (in seconds) at which a play event |
48 +--------------+----------+---------------------------------------------------+
49 | total | no | The total duratin (in seconds) of the media file |
50 +--------------+----------+---------------------------------------------------+
56 The following types of events (*actions*) are currently defined.
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
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
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).
75 Clients SHOULD aggregate events in upload them in batches.
81 To initiate an upload, the following request should be issued. ::
83 POST /user/<username>/events
84 Content-Tpe: application/json
94 Clients MUST NOT upload an empty list of events.
96 TODO: add ``default_data`` attribute to object, to avoid repeating the same
99 Clients MUST NOT upload invalid event objects.
101 If events reference devices that do not yet exist, they are automatically
102 created with default data.
104 TODO: specify device-id at top-level? what about events that don't belong to
105 any device? move device-id to URL?
111 The following responses are possible.
113 The uploaded list of events has been processed immediatelly ::
118 The uploaded list of events has been accepted for later processing ::
129 No payload data is returned as a response to uploading events.
135 Clients can download events to retrieve those that have been uploaded by other
136 devices (or itself) since a certain timestamp.
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.
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).
151 **Explicit Timestamp:** retrieve all events after a specific timestamp. ::
153 GET /user/<username>/events?since=<timestamp>
157 * since: numeric timestamp value (mandatory)
160 **Implicit Timestamp:** retrieve all events that the current device has not yet
161 seen. The timestamp of is stored on the server side. ::
163 GET /user/<username>/device/<device-id>/events
167 * reset: can be set to true to reset the server-side timestamp to 0 and
177 Content-Tpe: application/json
191 Response is being prepared ::
193 203 Found / 202 See Other
194 Link: /user/<username>/events/response/<id>
197 The server is preparing the result at the specified resource. The client should
198 try to fetch the data from the given URLs. ::
200 GET /user/<username>/events/<id>
201 Content-Tpe: application/json
204 A 404 might be returned before the data is ready. The client may retry after
210 When the data is ready, 200 will be returned ::
213 Content-Tpe: application/json
218 When the data is no longer available, a 410 is returned. ::
222 In this case the client SHOULD retry with the previous ``since`` value.
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
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.