4 Clients can use the gpodder.net API to store and exchange settings. Clients can
5 chose to simply store their settings on gpodder.net for online backup, or
6 exchange settings with other clients. Some settings also trigger behaviour on
7 the gpodder.net website.
9 Settings can be stored in several scopes. Each user has one *account* scope,
10 and one *device* scope per device. Additionally settings can be stored
11 per *podcast* and *episode*.
17 The Settings API defines the following resources ::
19 /user/{username}/settings/account
20 /user/{username}/settings/device
21 /user/{username}/settings/podcast
22 /user/{username}/settings/episode
28 Although settings are primarily used to exchange settings between clients, some
29 of them also trigger some behavior on the website.
35 The following settings are well-known in the account scope.
38 when set to False, sets all podcasts to private (as on
39 http://gpodder.net/account/privacy, currently deactivated via API)
42 allow gpodder.net to store the User-Agent for each
43 device (default: true)
45 **public_subscriptions**
46 default "public" value for subscriptions (default: true)
49 auth-token for a Flattr login; empty when not logged in (default: empty)
52 auto-flattr episodes, only relevant when logged into Flattr account
56 automatically flattr gpodder.net, only relevant when logged into Flattr
57 account (default: false)
60 username under which own items (eg podcast lists) are published
67 The following settings are well-known in the episode scope.
70 flags the episode as favorite (can be done on any episode-page)
76 The following settings are well-known in the podcast scope.
78 **public_subscription**
79 when set to False, sets the subscription to this podcast to private
80 (as on http://gpodder.net/account/privacy or any podcast-page, currently
89 POST /user/{username}/settings/{scope}{?scope_specification}
90 PATCH /user/{username}/settings/{scope}{?scope_specification}
93 * Requires authentication
100 can be either ``account``, ``device``, ``podcast`` or ``episode``
103 should contain the URL-encoded feed URL when ``scope`` is ``podcast`` or ``episode``
106 should contain the URL-encoded media URL when ``scope`` is ``episode``
109 should contain the device Id when ``scope`` is ``device``
115 The request body consists basically of a `JSON Patch (RFC 6902)
116 <http://tools.ietf.org/html/rfc6902>`_. However there are two possible
117 representations for a patch.
119 When the PATCH method is used, the body corresponds to the JSON Patch. ::
122 { "op": "test", "path": "/a/b/c", "value": "foo" },
123 { "op": "remove", "path": "/a/b/c" },
124 { "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] },
125 { "op": "replace", "path": "/a/b/c", "value": 42 },
126 { "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
127 { "op": "copy", "from": "/a/b/d", "path": "/a/b/e" }
131 When a POST request is used, a JSON object is included in the body, where the
132 actual patch is provided in the *patch* attribute. ::
136 { "op": "test", "path": "/a/b/c", "value": "foo" },
137 { "op": "remove", "path": "/a/b/c" },
138 { "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] },
139 { "op": "replace", "path": "/a/b/c", "value": 42 },
140 { "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
141 { "op": "copy", "from": "/a/b/d", "path": "/a/b/e" }
145 Please refer to `RFC 6902 <http://tools.ietf.org/html/rfc6902>`_ for the
146 allowed operations and exact semantics of JSON Patch. Previously unused
147 settings default to the empty JSON object (``{}``).
156 * 409 Conflict if a test operation failed
158 A positive response contains all settings that the scope has after the update
159 has been carried out. ::
162 "setting1": "value1",
173 GET /user/{username}/settings/{scope}{?scope_specification}
175 Scope and specification as above.
176 Requires Authentication
182 The response contains all settings that the scope currently has ::
184 {"setting1": "value1", "setting2": "value2"}