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/<device-id>/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/<device-id>/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/<device-id>/subscription?since=0>; rel=changes
60 If the subscriptions have been processed immediatelly ::
63 Link: <https://api.gpodder.net/user/<username>/device/<device-id>/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/<device-id>/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/<device-id>/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/<device-id>/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.
166 The server responds with either of the following status codes.
168 The changes are processed immediatelly. ::
171 Content-Tpe: application/json
173 body according to Subscription Download
176 The changes have been accepted for later processing. ::
182 No response body is provided in this case, as it is not yet known.
185 .. _subscription-change-download:
187 Subscription Change Download
188 ----------------------------
190 Download changes to the subscriptions of a device.
196 The client makes the following request. ::
198 GET /user/<username>/device/<device-id>/subscriptions?since=<since>
199 Content-Tpe: application/json
205 The server can response with any of the following status codes.
207 The changes are returned immediatelly. ::
210 Link: <https://api.gpodder.net/user/<username>/device/<device-id>/subscription?since=1234>; rel=changes
211 Content-Type: application/json
215 { url: "http://example.com/podcast.rss" }
218 { url: "http://podcast.com/episodes.xml" }
222 The server can also return a prepared response (see
223 :ref:`prepared-response-api`).