From 404d9fd79c5799f3558bcdbf735b51ee02a85c03 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Stefan=20K=C3=B6gl?= Date: Wed, 1 May 2013 10:01:00 +0200 Subject: [PATCH] Improve Events API draft --- doc/api/reference/events.rst | 170 ++++++++++++++++++++++++++++++++++++++++--- doc/api/usage.rst | 13 ++++ 2 files changed, 173 insertions(+), 10 deletions(-) diff --git a/doc/api/reference/events.rst b/doc/api/reference/events.rst index 2d168c11..b1074c2c 100644 --- a/doc/api/reference/events.rst +++ b/doc/api/reference/events.rst @@ -3,6 +3,12 @@ Events API ========== +The **Events API** can be used by clients to exchange information about the +status of podcast episodes. Clients upload events with certain actions such as +*play* to inform other clients that an episode has already been played. Clients +can receive episode actions, for example on startup, to update the status of +episodes accordingly. + Resources --------- @@ -10,45 +16,160 @@ Resources The Events API defines the following resources :: /user//events - /user//events/ + /user//events/response/ + /user//events/device/ + + +Event Data +---------- + +An event is a JSON object with the following attributes. + ++--------------+----------+---------------------------------------------------+ +| Attribute | Required | Values | ++==============+==========+===================================================+ +| action | yes | one of ``play``, ``download``, ``flattr``, | +| | | ``delete`` | ++--------------+----------+---------------------------------------------------+ +| timestamp | yes | The UTC timestamp at which the event occured as | +| | | `RFC 3339 `_ | ++--------------+----------+---------------------------------------------------+ +| podcast | yes | The feed URL of the podcast | ++--------------+----------+---------------------------------------------------+ +| episode | yes | The media URL of the episode | ++--------------+----------+---------------------------------------------------+ +| device | no | The device ID at which the event was triggered | ++--------------+----------+---------------------------------------------------+ +| started | no | The position (in seconds) at which a play event | +| | | started | ++--------------+----------+---------------------------------------------------+ +| positon | no | The position (in seconds) at which a play event | +| | | was stopped | ++--------------+----------+---------------------------------------------------+ +| total | no | The total duratin (in seconds) of the media file | ++--------------+----------+---------------------------------------------------+ + + +Event Types +^^^^^^^^^^^ + +The following types of events (*actions*) are currently defined. + +* *play*: the episode has been played +* *download*: the episode has been downloaded +* *flattr*: the episode has been flattered +* *delete*: the episode has been deleted + +Additional event types might be defined in the future. To ensure forward +compatability, clients should accept (in if necessary ignore) events of unknown +type. Upload Events ------------- -Request :: +Clients can upload new events to gpodder.net to make them available online and +for other clients. Clients MUST NOT upload events that have not been triggered +through them (ie events that have been donwloaded from the API). + +Clients SHOULD aggregate events in upload them in batches. + + +Request +^^^^^^^ + +To initiate an upload, the following request should be issued. :: POST /user//events Content-Tpe: application/json + { + events: [ + { event }, + { event }, + ... + ] + } + +Clients MUST NOT upload an empty list of events. + +TODO: add ``default_data`` attribute to object, to avoid repeating the same +data over and over? + +Clients MUST NOT upload invalid event objects. -Responses: +If events reference devices that do not yet exist, they are automatically +created with default data. -Processed immediatelly :: +TODO: specify device-id at top-level? what about events that don't belong to +any device? move device-id to URL? + + +Response +^^^^^^^^ + +The following responses are possible. + +The uploaded list of events has been processed immediatelly :: 204 No Content -Accepted for later processing :: +The uploaded list of events has been accepted for later processing :: 202 Accepted +TODO: Validation? + + +Data +^^^^ + +No payload data is returned as a response to uploading events. + Download Events --------------- +Clients can download events to retrieve those that have been uploaded by other +devices (or itself) since a certain timestamp. + +It is RECOMMENDED that clients do not persistently store events after they have +been uploaded. Instead they SHOULD download events after an upload, to retrieve +all events that they (and other clients) have uploaded. + + +Requests +^^^^^^^^ + +Download requests retrieve events that have been uploaded since a specific +timestamp. This timestamp can be given explicitly (if the corresponding +timestamp value is maintained) is implicitly by the device-id (the +server maintains a timestamp per device). + +**Explicit Timestamp:** retrieve all events after a specific timestamp. :: + + GET /user//events?since= + Parameters -* since (optional, default 0) +* since: numeric timestamp value (mandatory) -Request :: +**Implicit Timestamp:** retrieve all events that the current device has not yet +seen. The timestamp of is stored on the server side. :: - GET /user//events + GET /user//device//events +Parameters + +* reset: can be set to true to reset the server-side timestamp to 0 and + retrieve all events. -Responses. + +Responses +^^^^^^^^^ Response :: @@ -56,11 +177,21 @@ Response :: Content-Tpe: application/json TODO ...? + { + since: ..., + timestamp: ..., + events: [ + { event }, + { event }, + ... + ] + } + Response is being prepared :: 203 Found / 202 See Other - Link: /user//events/ + Link: /user//events/response/ The server is preparing the result at the specified resource. The client should @@ -88,4 +219,23 @@ When the data is no longer available, a 410 is returned. :: 410 Gone +In this case the client SHOULD retry with the previous ``since`` value. + +A successful response indicates a timeframe (between ``since`` and +``timestamp``) for which events have been retrieved. When using +*explicit* queries, the client MUST use the value of the last respone's +``timestamp`` field as the value of the ``since`` parameter in the following +request. The ``since`` paramter can be set to ``0`` if previously retrieved +events have been lost (eg through a database reset). This MUST, however, be an +exceptional case. + + +Data +^^^^ +The client can expect the retrieved events to be well-formed but SHOULD be able +to at least safely ignore invalid events. This includes events with an +``action`` which is not listed above. While the API does perform input +validation on uploaded events, this should ensure that clients are able to +remain operational if for example new event types are introduced which have +different requirements to the provided attributes. diff --git a/doc/api/usage.rst b/doc/api/usage.rst index 751ce77b..4afac1e3 100644 --- a/doc/api/usage.rst +++ b/doc/api/usage.rst @@ -57,3 +57,16 @@ certain feature. +------------------------+---------------+----------------+ | Settings | unlimited | +1000 | +------------------------+---------------+----------------+ + + +Misbehaving Clients +------------------- + +Violations of rules that are given as *MUST* or *MUST NOT* are recorded. Any +client application may accumulate 100 of such violations per day (to accomodate +for bug fixing and debugging). Client applications that regularly +exceed this limit will be blocked. The status (and reports) of a client +application's violations can be viewed online. TODO: where? + + +TODO: distinguish between (individual) clients and client applications. -- 2.11.4.GIT