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 The first resource represents the summary of subscriptions over all devices. It
  19 can not be modified directly.
  20
  21 The second resource represents the subscriptions of a single
  22 :ref:`device-integration`.
  23
  24
  25 Subscription Upload
  26 -------------------
  27
  28 Clients can upload the podcast subscriptions for a :ref:`device-integration` to
  29 replace its existing subscriptions.
  30
  31
  32 Request
  33 ^^^^^^^
  34
  35 The client sends an object containing all current subscriptions for the
  36 device. ::
  37
  38  PUT /user/{username}/device/{deviceid}/subscriptions
  39  Content-Type: application/json
  40
  41  {
  42     podcasts: [
  43         { url: "http://example.com/podcast.rss" },
  44         { url: "http://podcast.com/episodes.xml" }
  45     ]
  46  }
  47
  48
  49 Response
  50 ^^^^^^^^
  51
  52 The server can respond with the following status codes.
  53
  54 If a ``Link`` header with ``rel=changes`` is provided, this URL can be used to
  55 retrieve changes to the subscriptions since the respective response (see
  56 :ref:`subscription-change-download`)
  57
  58 If a new device has been created ::
  59
  60  201 Created
  61  Link: <https://api.gpodder.net/user/{username}/device/{deviceid}/subscription?since=0>; rel=changes
  62
  63  no body
  64
  65
  66 If the subscriptions have been processed immediatelly ::
  67
  68  204 No Content
  69  Link: <https://api.gpodder.net/user/{username}/device/{deviceid}/subscription?since=1234>; rel=changes
  70
  71  no body
  72
  73
  74 If the subscriptions have been accepted for later processing ::
  75
  76  202 Accepted
  77
  78  no body
  79
  80 No change download address is provided in this case, as is is not yet known at
  81 the time of the response. If the client needs to know the current
  82 subscriptions, it should follow up by a request to download the subscriptions.
  83
  84 If invalid podcast information is provided (eg an invalid feed URL), the whole
  85 request will be rejected. ::
  86
  87  400 Bad Request
  88  Content-Type: application/json
  89
  90  {
  91    "message": "Invalid podcast URL",
  92    "errors": [
  93      {
  94        "field": "/podcasts/1",
  95        "code": "invalid_url"
  96      }
  97    ]
  98  }
  99
 100
 101 Subscription Download
 102 ---------------------
 103
 104 Clients can download the current subscriptions either of a single
 105 :ref:`device-integration` or over all of the user's devices.
 106
 107
 108 Request
 109 ^^^^^^^
 110
 111 Download subscriptions of a device ::
 112
 113  GET /user/{username}/device/{deviceid}/subscriptions
 114  Content-Type: application/json
 115
 116
 117 Download all of the user's subscriptions ::
 118
 119  GET /user/{username}/subscriptions
 120  Content-Type: application/json
 121
 122
 123 Response
 124 ^^^^^^^^
 125
 126 The podcasts correspond to the :ref:`podcast-type` type. ::
 127
 128  200 OK
 129  Link: <https://api.gpodder.net/user/{username}/device/{deviceid}/subscription?since=1234>; rel=changes
 130  Content-Type: application/json
 131
 132  {
 133     podcasts: [
 134         { podcast1 },
 135         { podcast2 }
 136     ]
 137  }
 138
 139 The changes link is not provided if all subscriptions of a user are requested.
 140
 141
 142 Subscription Change Upload
 143 --------------------------
 144
 145 Clients can update the current subscriptions of a :ref:`device-integration` by
 146 reporting subscribed and unsubscribed podcasts.
 147
 148
 149 Request
 150 ^^^^^^^
 151
 152 A client can send which podcasts have been subscribed and unsubscribed. ::
 153
 154  POST /user/{username}/device/{deviceid}/subscriptions
 155  Content-Tpe: application/json
 156
 157  {
 158     subscribe: [
 159         { url: "http://example.com/podcast.rss" }
 160     ]
 161     unsubscribe: [
 162         { url: "http://podcast.com/episodes.xml" }
 163     ]
 164  }
 165
 166 A client MUST NOT upload a change set where both ``subscribe`` and
 167 ``unsubscribe`` are empty, or where the same podcast is given in both
 168 ``subscribe`` and ``unsubscribe``.
 169
 170
 171 Response
 172 ^^^^^^^^
 173
 174 The server responds with either of the following status codes.
 175
 176 The changes are processed immediatelly. ::
 177
 178  200 OK
 179  Content-Tpe: application/json
 180
 181  body according to Subscription Download
 182
 183
 184 The changes have been accepted for later processing. ::
 185
 186  204 Accepted
 187
 188  no body
 189
 190 No response body is provided in this case, as it is not yet known.
 191
 192
 193 .. _subscription-change-download:
 194
 195 Subscription Change Download
 196 ----------------------------
 197
 198 Download changes to the subscriptions of a :ref:`device-integration`.
 199
 200
 201 Request
 202 ^^^^^^^
 203
 204 The client makes the following request. ::
 205
 206  GET /user/{username}/device/{deviceid}/subscriptions{?since}
 207  Content-Tpe: application/json
 208
 209
 210 Response
 211 ^^^^^^^^
 212
 213 The server can response with any of the following status codes.
 214
 215 The changes are returned immediatelly. ::
 216
 217  200 OK
 218  Link: <https://api.gpodder.net/user/{username}/device/{deviceid}/subscription?since=1234>; rel=changes
 219  Content-Type: application/json
 220
 221  {
 222     subscribe: [
 223         { url: "http://example.com/podcast.rss" }
 224     ]
 225     unsubscribe: [
 226         { url: "http://podcast.com/episodes.xml" }
 227     ]
 228  }
 229
 230 The server can also return a prepared response (see
 231 :ref:`prepared-response-api`).
 232
 233
 234 Integration Recommendations
 235 ---------------------------
 236
 237 This section describes how the API can be accessed for common use cases.
 238
 239 * On first startup a client CAN retrieve the list of all the user's
 240   subscriptions to offer as suggestions.
 241
 242 * On first startup a client SHOULD generate a unique :ref:`device-integration`
 243   Id for managing its own subscriptions in subsequent API calls.
 244
 245 * A client which has been somehow "reset" can re-use an existing device ID and
 246   restore its subscriptions from there. It SHOULD NOT share the same device ID
 247   with another installation which is still used.
 248
 249 * A client SHOULD either use the combination of Subscription Upload and
 250   Download endpoints, or the Subscription Change endpoints to keep its
 251   subscriptions up to date.
 252
 253 * When retrieving subscriptions or subscription changes, a client SHOULD use
 254   the URL in the ``Link`` header with ``rel=changes`` (if present) to retrieve
 255   subsequent changes to the resource.