api-docs/reference/subscriptions.rst

   1 .. _subscriptions-api:
   2
   3 Subscriptions API
   4 =================
   5
   6 The subscriptions API is used to manage the podcast subscriptions of a client
   7 device.
   8
   9
  10 Resources
  11 ---------
  12
  13 The Subscriptions API defines the following resources ::
  14
  15  /<username>/subscriptions
  16  /<username>/device/<device-id>/subscriptions
  17
  18
  19 Subscription Upload
  20 -------------------
  21
  22 Upload the subscriptions for a device ::
  23
  24  PUT /<username>/device/<device-id>/subscriptions
  25  Content-Tpe: application/json
  26
  27  TODO: specify body
  28
  29
  30 The server can respond with the following status codes.
  31
  32 When a new device has been created ::
  33
  34  201 Created
  35  Link: <https://api.gpodder.net/<username>/device/<device-id>/subscription?since=0>; rel=changes
  36  ...
  37
  38
  39 When the subscriptions have been processed immediatelly ::
  40
  41  204 No Content
  42  Link: <https://api.gpodder.net/<username>/device/<device-id>/subscription?since=1234>; rel=changes
  43  ...
  44
  45
  46 When the subscriptions have been accepted for later processing ::
  47
  48  202 Accepted
  49  Link: <https://api.gpodder.net/<username>/device/<device-id>/subscription?since=1234>; rel=changes
  50  ...
  51  TODO: return change download address here?
  52
  53
  54 Any status code >= 200 and < 300 should be considered a success.
  55
  56 TODO: specify body?
  57
  58
  59 Subscription Download
  60 ---------------------
  61
  62 Download subscriptions of a device ::
  63
  64  GET /<username>/device/<device-id>/subscriptions
  65  Content-Type: application/json
  66
  67  200 Found
  68  Link: <https://api.gpodder.net/<username>/device/<device-id>/subscription?since=1234>; rel=changes
  69  Content-Type: application/json
  70  Last-Modified: ...
  71
  72  {
  73      "add": [{ "url": "..."}, { ...}]
  74      "timestamp": 1234,
  75  }
  76
  77
  78 Download all of the users subscriptions ::
  79
  80  GET /<username>/subscriptions
  81  Content-Type: application/json
  82
  83  200 Found
  84  Link: <https://api.gpodder.net/<username>/device/<device-id>/subscription?since=1234>; rel=changes
  85  Content-Type: application/json
  86  Last-Modified: ...
  87
  88  TODO: specify body
  89
  90
  91 Subscription Change Upload
  92 --------------------------
  93
  94 Upload changes to the subscriptions of a device ::
  95
  96  POST /<username>/device/<device-id>/subscriptions
  97  Content-Tpe: application/json
  98
  99  TODO: specify body...
 100
 101
 102
 103 Subscription Change Download
 104 ----------------------------
 105
 106 Download changes to the subscriptions of a device ::
 107
 108  GET /<username>/device/<device-id>/subscriptions?since=<since>
 109  Content-Tpe: application/json
 110
 111  200 Found
 112  Link: <https://api.gpodder.net/<username>/device/<device-id>/subscription?since=1234>; rel=changes
 113  Content-Type: application/json
 114  Last-Modified: ...
 115
 116  TODO: specify body...
 117
 118