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 The server can also return a prepared response (see
192 :ref:`prepared-response-api`).
194 A successful response indicates a timeframe (between ``since`` and
195 ``timestamp``) for which events have been retrieved. When using
196 *explicit* queries, the client MUST use the value of the last respone's
197 ``timestamp`` field as the value of the ``since`` parameter in the following
198 request. The ``since`` paramter can be set to ``0`` if previously retrieved
199 events have been lost (eg through a database reset). This MUST, however, be an
206 The client can expect the retrieved events to be well-formed but SHOULD be able
207 to at least safely ignore invalid events. This includes events with an
208 ``action`` which is not listed above. While the API does perform input
209 validation on uploaded events, this should ensure that clients are able to
210 remain operational if for example new event types are introduced which have
211 different requirements to the provided attributes.