doc/api/usage.rst

   1 API Usage
   2 =========
   3
   4
   5 Client Registration
   6 -------------------
   7
   8 Most API endpoints can only be accessed by registered clients using a client
   9 key. Clients can be registered for free at LINK.
  10
  11 TODO: User-Agent?
  12
  13
  14 Allowed Usage
  15 -------------
  16
  17 **Open source clients** can issue an unlimited number of requests to the API.
  18
  19 **Closed source Clients** (this includes free-of-charge closed source clients)
  20 have a quota of requests per day (UTC). The quota depends on the features
  21 they implement (and activate/enable by default).
  22
  23 If there are open and closed sourced versions of a client, they need to have
  24 two API keys.
  25
  26 The following table shows how the client quota is increased by implementing a
  27 certain feature.
  28
  29 +------------------------+---------------+----------------+
  30 | Features               | Open source   | Closed source  |
  31 +========================+===============+================+
  32 | Podcast Search         | unlimited     | unlimited      |
  33 +------------------------+---------------+----------------+
  34 | Podcast Toplist        | unlimited     | +1000          |
  35 +------------------------+---------------+----------------+
  36 | Top Tags               | unlimited     | +1000          |
  37 +------------------------+---------------+----------------+
  38 | Tag-Podcasts           | unlimited     | +1000          |
  39 +------------------------+---------------+----------------+
  40 | Subscriptions Download | unlimited     | +1000          |
  41 +------------------------+---------------+----------------+
  42 | Subscriptions Upload   | unlimited     | +5000          |
  43 +------------------------+---------------+----------------+
  44 | Device List and Config | unlimited     | +1000          |
  45 +------------------------+---------------+----------------+
  46 | Episode Favorites      | unlimited     | +1000          |
  47 +------------------------+---------------+----------------+
  48 | Authentication         | unlimited     | unlimited      |
  49 +------------------------+---------------+----------------+
  50 | Device Sync            | unlimited     | +1000          |
  51 +------------------------+---------------+----------------+
  52 | Events Upload          | unlimited     | +10000         |
  53 +------------------------+---------------+----------------+
  54 | Events Download        | unlimited     | +10000         |
  55 +------------------------+---------------+----------------+
  56 | Podcast Lists          | unlimited     | +1000          |
  57 +------------------------+---------------+----------------+
  58 | Settings               | unlimited     | +1000          |
  59 +------------------------+---------------+----------------+
  60
  61
  62 Misbehaving Clients
  63 -------------------
  64
  65 Violations of rules that are given as *MUST* or *MUST NOT* are recorded. Any
  66 client application may accumulate 100 of such violations per day (to accomodate
  67 for bug fixing and debugging). Client applications that regularly
  68 exceed this limit will be blocked. The status (and reports) of a client
  69 application's violations can be viewed online. TODO: where?
  70
  71
  72 TODO: distinguish between (individual) clients and client applications.