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
  91
  92 * Requires authentication
  93
  94
  95 Parameters
  96 ^^^^^^^^^^
  97
  98 **scope**
  99   can be either ``account``, ``device``, ``podcast`` or ``episode``
 100
 101 **podcast**
 102   should contain the URL-encoded feed URL when ``scope`` is ``podcast`` or ``episode``
 103
 104 **episode**
 105   should contain the URL-encoded media URL when ``scope`` is ``episode``
 106
 107 **device**
 108   should contain the device Id when ``scope`` is ``device``
 109
 110
 111 Request Body
 112 ^^^^^^^^^^^^
 113
 114 TODO: JSON-Patch ?
 115
 116 Post-Data ::
 117
 118     {
 119      "set": {"setting1": "value1", "setting2": "value2"},
 120      "remove": ["setting3", "setting4"]
 121     }
 122
 123 set is a dictionary of settings to add or update; remove is a list of keys that
 124 shall be removed from the scope.
 125
 126 Response
 127 ^^^^^^^^
 128
 129 The response contains all settings that the scope has after the update has been
 130 carried out. ::
 131
 132     {
 133      "setting1": "value1",
 134      "setting2": "value"
 135     }
 136
 137
 138
 139 Get Settings
 140 ------------
 141
 142 Get Settings ::
 143
 144     GET /user/<username>/settings/<scope>?<scope-specification>
 145
 146 Scope and specification as above.
 147 Requires Authentication
 148
 149
 150 Response
 151 ^^^^^^^^
 152
 153 The response contains all settings that the scope currently has ::
 154
 155     {"setting1": "value1", "setting2": "value2"}