doc/api/reference/devices.rst

   1 Device API
   2 ==========
   3
   4 .. _api-device-data-set:
   5
   6 Update Device Data
   7 ------------------
   8
   9 ..  http:post:: /api/2/devices/(username)/(deviceid).json
  10     :synopsis: Sets the name and type of the device.
  11
  12     * Requires HTTP authentication
  13     * Since 2.0
  14
  15     The device ID is generated by the client application to identify itself in
  16     API requests. The name is used to display a human readable identifier to
  17     the user on the webservice. Only the keys that are supplied will be
  18     updated.
  19
  20     **Example request**:
  21
  22     .. sourcecode:: http
  23
  24         POST /api/2/devices/a-user/somedevice-123.json
  25
  26         {
  27             "caption": "gPodder on my Lappy",
  28             "type": "laptop"
  29         }
  30
  31     :param username: the username for which device data should be updated
  32     :param deviceid: see :ref:`devices`
  33     :<json string caption: The new human readable label for the device
  34     :<json string type: he type of the device. Possible values: desktop, laptop, mobile, server, other
  35
  36
  37
  38 .. _api-device-list:
  39
  40 List Devices
  41 ------------
  42
  43 ..  http:post:: /api/2/devices/(username).json
  44     :synopsis: list the user's devices
  45
  46     * Requires HTTP authentication
  47     * Since 2.0
  48
  49     Returns the list of devices that belong to a user. This can be used by the
  50     client to let the user select a device from which to retrieve
  51     subscriptions, etc..
  52
  53     **Example response**:
  54
  55     .. sourcecode:: http
  56
  57         HTTP/1.1 200 OK
  58
  59         [
  60           {
  61            "id": "abcdef",
  62            "caption": "gPodder on my Lappy",
  63            "type": "laptop",
  64            "subscriptions": 27
  65           },
  66           {
  67            "id": "09jc23caf",
  68            "caption": "",
  69            "type": "other",
  70            "subscriptions": 30
  71           },
  72           {
  73            "id": "phone-au90f923023.203f9j23f",
  74            "caption": "My Phone",
  75            "type": "mobile",
  76            "subscriptions": 5
  77           }
  78         ]
  79
  80     :param username: the username for which the devices should be returned
  81
  82
  83 .. _api-device-updates:
  84
  85 Get Device Updates
  86 ------------------
  87
  88 ..  http:get:: /api/2/updates/(username)/(deviceid).json
  89     :synopsis: returns episode and subscription updates for the given device
  90
  91     * Requires Authentication
  92     * Since 2.3
  93
  94     **Example response**:
  95
  96     .. sourcecode:: http
  97
  98         HTTP/1.1 200 OK
  99
 100         {
 101             "add":     [
 102             {
 103                "title": "PaulDotCom Security Weekly",
 104                "url": "http://pauldotcom.com/podcast/psw.xml",
 105                "description": "PaulDotCom Security Weekly Podcast with Paul, Larry, Mick, Carlos, and special guests!",
 106                "subscribers": 93,
 107                "logo_url": "http://pauldotcom.com/images/psw-logo-sm.png"
 108                "website": "http://pauldotcom.com/",
 109                "mygpo_link": "http://gpodder.net/podcast/11194",
 110             }
 111           ],
 112
 113           "remove":  ["<URL3>"],
 114
 115           "updates": [
 116             {
 117               "title": "TWiT 245: No Hitler For You",
 118               "url": "http://www.podtrac.com/pts/redirect.mp3/aolradio.podcast.aol.com/twit/twit0245.mp3",
 119               "podcast_title": "this WEEK in TECH - MP3 Edition",
 120               "podcast_url": "http://leo.am/podcasts/twit",
 121               "description": "[...]",
 122               "website": "http://www.podtrac.com/pts/redirect.mp3/aolradio.podcast.aol.com/twit/twit0245.mp3",
 123               "mygpo_link": "http://gpodder.net/episode/1046492"
 124               "released":   """2009-12-12T09:00:00"
 125               "status":        "(new|play|download|delete)"
 126              }
 127             ],
 128
 129            "timestamp":   <timestamp>
 130         }
 131
 132     :query since: ``timestamp`` when updates have last been retrieved
 133     :query bool include_actions: Default: false, since 2.10
 134
 135     The response will have the following form and will contain
 136
 137     * a list of subscriptions to be added, with URL, title and descriptions
 138     * a list of URLs to be unsubscribed
 139     * a list of updated episodes
 140     * the current timestamp; for retrieving changes since the last query
 141
 142     If include_actions is set to true, each updated episode (with a state other
 143     than new) will contain an additional property action which includes
 144     the user's latest episode action reported for this episode. The actions
 145     have the same format as in :ref:`episode-action-types`.
 146