doc/api/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  /user/<username>/subscriptions
  16  /user/<username>/device/<device-id>/subscriptions
  17
  18
  19 Subscription Upload
  20 -------------------
  21
  22 Clients can upload the podcast subscriptions for a device to replace any
  23 existing subscriptions.
  24
  25
  26 Request
  27 ^^^^^^^
  28
  29 The client sends an object containing all current subscriptions for the
  30 device. ::
  31
  32  PUT /user/<username>/device/<device-id>/subscriptions
  33  Content-Type: application/json
  34
  35  {
  36     podcasts: [
  37         { url: "http://example.com/podcast.rss" },
  38         { url: "http://podcast.com/episodes.xml" }
  39     ]
  40  }
  41
  42
  43 Response
  44 ^^^^^^^^
  45
  46 The server can respond with the following status codes.
  47
  48 If a ``Link`` header with ``rel=changes`` is provided, this URL can be used to
  49 retrieve changes to the subscriptions since the respective response (see
  50 :ref:`subscription-change-download`)
  51
  52 If a new device has been created ::
  53
  54  201 Created
  55  Link: <https://api.gpodder.net/user/<username>/device/<device-id>/subscription?since=0>; rel=changes
  56
  57  no body
  58
  59
  60 If the subscriptions have been processed immediatelly ::
  61
  62  204 No Content
  63  Link: <https://api.gpodder.net/user/<username>/device/<device-id>/subscription?since=1234>; rel=changes
  64
  65  no body
  66
  67
  68 If the subscriptions have been accepted for later processing ::
  69
  70  202 Accepted
  71
  72  no body
  73
  74 No change download address is provided in this case, as is is not yet known at
  75 the time of the response. If the client needs to know the current
  76 subscriptions, it should follow up by a request to download the subscriptions.
  77
  78 If invalid podcast information is provided (eg an invalid feed URL), the whole
  79 request will be rejected. ::
  80
  81  400 Bad Request
  82  Content-Type: application/json
  83
  84  {
  85    "message": "Invalid podcast URL",
  86    "errors": [
  87      {
  88        "field": "/podcasts/1",
  89        "code": "invalid_url"
  90      }
  91    ]
  92  }
  93
  94
  95 Subscription Download
  96 ---------------------
  97
  98 Clients can download the current subscriptions of a device.
  99
 100
 101 Request
 102 ^^^^^^^
 103
 104 Download subscriptions of a device ::
 105
 106  GET /user/<username>/device/<device-id>/subscriptions
 107  Content-Type: application/json
 108
 109
 110 Download all of the user's subscriptions ::
 111
 112  GET /user/<username>/subscriptions
 113  Content-Type: application/json
 114
 115
 116 Response
 117 ^^^^^^^^
 118
 119 The podcasts correspond to the :ref:`podcast-type` type. ::
 120
 121  200 OK
 122  Link: <https://api.gpodder.net/user/<username>/device/<device-id>/subscription?since=1234>; rel=changes
 123  Content-Type: application/json
 124
 125  {
 126     podcasts: [
 127         { podcast1 },
 128         { podcast2 }
 129     ]
 130  }
 131
 132 The changes link is not provided if all subscriptions of a user are requested.
 133
 134
 135 Subscription Change Upload
 136 --------------------------
 137
 138 Clients can update the current subscriptions of a device by reporting
 139 subscribed and unsubscribed podcasts.
 140
 141
 142 Request
 143 ^^^^^^^
 144
 145 A client can send which podcasts have been subscribed and unsubscribed. ::
 146
 147  POST /user/<username>/device/<device-id>/subscriptions
 148  Content-Tpe: application/json
 149
 150  {
 151     subscribe: [
 152         { url: "http://example.com/podcast.rss" }
 153     ]
 154     unsubscribe: [
 155         { url: "http://podcast.com/episodes.xml" }
 156     ]
 157  }
 158
 159 A client MUST NOT upload a change set where both ``subscribe`` and
 160 ``unsubscribe`` are empty.
 161
 162
 163 Response
 164 ^^^^^^^^
 165
 166 The server responds with either of the following status codes.
 167
 168 The changes are processed immediatelly. ::
 169
 170  200 OK
 171  Content-Tpe: application/json
 172
 173  body according to Subscription Download
 174
 175
 176 The changes have been accepted for later processing. ::
 177
 178  204 Accepted
 179
 180  no body
 181
 182 No response body is provided in this case, as it is not yet known.
 183
 184
 185 .. _subscription-change-download:
 186
 187 Subscription Change Download
 188 ----------------------------
 189
 190 Download changes to the subscriptions of a device.
 191
 192
 193 Request
 194 ^^^^^^^
 195
 196 The client makes the following request. ::
 197
 198  GET /user/<username>/device/<device-id>/subscriptions?since=<since>
 199  Content-Tpe: application/json
 200
 201
 202 Response
 203 ^^^^^^^^
 204
 205 The server can response with any of the following status codes.
 206
 207 The changes are returned immediatelly. ::
 208
 209  200 OK
 210  Link: <https://api.gpodder.net/user/<username>/device/<device-id>/subscription?since=1234>; rel=changes
 211  Content-Type: application/json
 212
 213  {
 214     subscribe: [
 215         { url: "http://example.com/podcast.rss" }
 216     ]
 217     unsubscribe: [
 218         { url: "http://podcast.com/episodes.xml" }
 219     ]
 220  }
 221
 222 The server can also return a prepared response (see
 223 :ref:`prepared-response-api`).