doc/api/reference/settings.rst

   1 Settings API
   2 ============
   3
   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.
   8
   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*.
  12
  13
  14 Resources
  15 ---------
  16
  17 The Settings API defines the following resources ::
  18
  19     /user/{username}/settings/account
  20     /user/{username}/settings/device
  21     /user/{username}/settings/podcast
  22     /user/{username}/settings/episode
  23
  24
  25 Well-Known Settings
  26 -------------------
  27
  28 Although settings are primarily used to exchange settings between clients, some
  29 of them also trigger some behavior on the website.
  30
  31
  32 Account scope
  33 ^^^^^^^^^^^^^
  34
  35 The following settings are well-known in the account scope.
  36
  37 **public_profile**
  38     when set to False, sets all podcasts to private (as on
  39     http://gpodder.net/account/privacy, currently deactivated via API)
  40
  41 **store_user_agent**
  42     allow gpodder.net to store the User-Agent for each
  43     device (default: true)
  44
  45 **public_subscriptions**
  46     default "public" value for subscriptions (default: true)
  47
  48 **flattr_token**
  49     auth-token for a Flattr login; empty when not logged in (default: empty)
  50
  51 **auto_flattr**
  52     auto-flattr episodes, only relevant when logged into Flattr account
  53     (default: false)
  54
  55 **flattr_mygpo**
  56     automatically flattr gpodder.net, only relevant when logged into Flattr
  57     account (default: false)
  58
  59 **flattr_username**
  60     username under which own items (eg podcast lists) are published
  61     (default: empty)
  62
  63
  64 Episode scope
  65 ^^^^^^^^^^^^^
  66
  67 The following settings are well-known in the episode scope.
  68
  69 **is_favorite**
  70     flags the episode as favorite (can be done on any episode-page)
  71
  72
  73 Podcast scope
  74 ^^^^^^^^^^^^^
  75
  76 The following settings are well-known in the podcast scope.
  77
  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
  81     deactivated via API)
  82
  83
  84 Saving Settings
  85 ---------------
  86
  87 Save Settings ::
  88
  89     POST /user/{username}/settings/{scope}{?scope_specification}
  90     PATCH /user/{username}/settings/{scope}{?scope_specification}
  91
  92
  93 * Requires authentication
  94
  95
  96 Parameters
  97 ^^^^^^^^^^
  98
  99 **scope**
 100   can be either ``account``, ``device``, ``podcast`` or ``episode``
 101
 102 **podcast**
 103   should contain the URL-encoded feed URL when ``scope`` is ``podcast`` or ``episode``
 104
 105 **episode**
 106   should contain the URL-encoded media URL when ``scope`` is ``episode``
 107
 108 **device**
 109   should contain the device Id when ``scope`` is ``device``
 110
 111
 112 Request Body
 113 ^^^^^^^^^^^^
 114
 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.
 118
 119 When the PATCH method is used, the body corresponds to the JSON Patch. ::
 120
 121    [
 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" }
 128    ]
 129
 130
 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. ::
 133
 134     {
 135         patch: [
 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" }
 142         ]
 143     }
 144
 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 (``{}``).
 148
 149
 150 Response
 151 ^^^^^^^^
 152
 153 Status Codes:
 154
 155 * 200 OK
 156 * 409 Conflict if a test operation failed
 157
 158 A positive response contains all settings that the scope has after the update
 159 has been carried out. ::
 160
 161     {
 162      "setting1": "value1",
 163      "setting2": "value"
 164     }
 165
 166
 167
 168 Get Settings
 169 ------------
 170
 171 Get Settings ::
 172
 173     GET /user/{username}/settings/{scope}{?scope_specification}
 174
 175 Scope and specification as above.
 176 Requires Authentication
 177
 178
 179 Response
 180 ^^^^^^^^
 181
 182 The response contains all settings that the scope currently has ::
 183
 184     {"setting1": "value1", "setting2": "value2"}