[Tests] Test slug functionality, fix Slug ordering
[mygpo.git] / doc / api / usage.rst
blobd97ed5dfbd9bcf93d2d31ac0b114ef63ecf84e3f
1 .. _usage:
3 API Usage
4 =========
6 This page describes how the gpodder.net API can be used.
9 Client Registration
10 -------------------
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.
16 TODO: User-Agent?
18 TODO: how is the API Key included in requests?
21 Allowed Usage
22 -------------
24 **Open source clients** can issue an unlimited number of requests to the API.
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).
30 If there are open and closed sourced versions of a client, they need to have
31 two API keys.
33 The following table shows how the client quota is increased by implementing a
34 certain feature.
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 +------------------------+---------------+----------------+
71 Misbehaving Clients
72 -------------------
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?
81 TODO: distinguish between (individual) clients and client applications.