6 The subscriptions API is used to manage the podcast subscriptions of a client
13 The Subscriptions API defines the following resources ::
15 /user/{username}/subscriptions
16 /user/{username}/device/{deviceid}/subscriptions
22 Clients can upload the podcast subscriptions for a device to replace any
23 existing subscriptions.
29 The client sends an object containing all current subscriptions for the
32 PUT /user/{username}/device/{deviceid}/subscriptions
33 Content-Type: application/json
37 { url: "http://example.com/podcast.rss" },
38 { url: "http://podcast.com/episodes.xml" }
46 The server can respond with the following status codes.
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`)
52 If a new device has been created ::
55 Link: <https://api.gpodder.net/user/{username}/device/{deviceid}/subscription?since=0>; rel=changes
60 If the subscriptions have been processed immediatelly ::
63 Link: <https://api.gpodder.net/user/{username}/device/{deviceid}/subscription?since=1234>; rel=changes
68 If the subscriptions have been accepted for later processing ::
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.
78 If invalid podcast information is provided (eg an invalid feed URL), the whole
79 request will be rejected. ::
82 Content-Type: application/json
85 "message": "Invalid podcast URL",
88 "field": "/podcasts/1",
98 Clients can download the current subscriptions of a device.
104 Download subscriptions of a device ::
106 GET /user/{username}/device/{deviceid}/subscriptions
107 Content-Type: application/json
110 Download all of the user's subscriptions ::
112 GET /user/{username}/subscriptions
113 Content-Type: application/json
119 The podcasts correspond to the :ref:`podcast-type` type. ::
122 Link: <https://api.gpodder.net/user/{username}/device/{deviceid}/subscription?since=1234>; rel=changes
123 Content-Type: application/json
132 The changes link is not provided if all subscriptions of a user are requested.
135 Subscription Change Upload
136 --------------------------
138 Clients can update the current subscriptions of a device by reporting
139 subscribed and unsubscribed podcasts.
145 A client can send which podcasts have been subscribed and unsubscribed. ::
147 POST /user/{username}/device/{deviceid}/subscriptions
148 Content-Tpe: application/json
152 { url: "http://example.com/podcast.rss" }
155 { url: "http://podcast.com/episodes.xml" }
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``.
167 The server responds with either of the following status codes.
169 The changes are processed immediatelly. ::
172 Content-Tpe: application/json
174 body according to Subscription Download
177 The changes have been accepted for later processing. ::
183 No response body is provided in this case, as it is not yet known.
186 .. _subscription-change-download:
188 Subscription Change Download
189 ----------------------------
191 Download changes to the subscriptions of a device.
197 The client makes the following request. ::
199 GET /user/{username}/device/{deviceid}/subscriptions{?since}
200 Content-Tpe: application/json
206 The server can response with any of the following status codes.
208 The changes are returned immediatelly. ::
211 Link: <https://api.gpodder.net/user/{username}/device/{deviceid}/subscription?since=1234>; rel=changes
212 Content-Type: application/json
216 { url: "http://example.com/podcast.rss" }
219 { url: "http://podcast.com/episodes.xml" }
223 The server can also return a prepared response (see
224 :ref:`prepared-response-api`).