doc/api/usage.rst

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