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/{deviceid}/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/{deviceid}/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/{deviceid}/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/{deviceid}/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/{deviceid}/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/{deviceid}/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/{deviceid}/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, or where the same podcast is given in both
 161 ``subscribe`` and ``unsubscribe``.
 162
 163
 164 Response
 165 ^^^^^^^^
 166
 167 The server responds with either of the following status codes.
 168
 169 The changes are processed immediatelly. ::
 170
 171  200 OK
 172  Content-Tpe: application/json
 173
 174  body according to Subscription Download
 175
 176
 177 The changes have been accepted for later processing. ::
 178
 179  204 Accepted
 180
 181  no body
 182
 183 No response body is provided in this case, as it is not yet known.
 184
 185
 186 .. _subscription-change-download:
 187
 188 Subscription Change Download
 189 ----------------------------
 190
 191 Download changes to the subscriptions of a device.
 192
 193
 194 Request
 195 ^^^^^^^
 196
 197 The client makes the following request. ::
 198
 199  GET /user/{username}/device/{deviceid}/subscriptions{?since}
 200  Content-Tpe: application/json
 201
 202
 203 Response
 204 ^^^^^^^^
 205
 206 The server can response with any of the following status codes.
 207
 208 The changes are returned immediatelly. ::
 209
 210  200 OK
 211  Link: <https://api.gpodder.net/user/{username}/device/{deviceid}/subscription?since=1234>; rel=changes
 212  Content-Type: application/json
 213
 214  {
 215     subscribe: [
 216         { url: "http://example.com/podcast.rss" }
 217     ]
 218     unsubscribe: [
 219         { url: "http://podcast.com/episodes.xml" }
 220     ]
 221  }
 222
 223 The server can also return a prepared response (see
 224 :ref:`prepared-response-api`).