Browse Source

First commit

pjc 7 months ago
commit
4714c89fac
7 changed files with 779 additions and 0 deletions
  1. 92
    0
      docs/forums.md
  2. 153
    0
      docs/index.md
  3. 86
    0
      docs/meta.md
  4. 50
    0
      docs/requests.md
  5. 156
    0
      docs/torrents.md
  6. 241
    0
      docs/users.md
  7. 1
    0
      mkdocs.yml

+ 92
- 0
docs/forums.md View File

@@ -0,0 +1,92 @@
1
+# Forums
2
+
3
+Endpoints related to the forums.
4
+
5
+
6
+## Category view
7
+
8
+**Request**
9
+
10
+`ajax.php?action=forum&type=main`
11
+
12
+
13
+**Response**
14
+
15
+```json
16
+
17
+```
18
+
19
+
20
+## Forum view
21
+
22
+**Request**
23
+
24
+`ajax.php?action=forum&type=viewforum`
25
+
26
+`&forumid=` — id of the forum to display (required)
27
+
28
+`&page=` — the page to display (default: `1`)
29
+
30
+
31
+**Response**
32
+
33
+```json
34
+
35
+```
36
+
37
+
38
+## Thread view 
39
+
40
+**Request**
41
+
42
+`ajax.php?action=forum&type=viewthread`
43
+
44
+`&threadid=` — id of the thread to display (required)
45
+
46
+`&postid=` — response will be the page including the post with this id
47
+
48
+`&page=` — page to display (default: `1`)
49
+
50
+`&updatelastread=` — set to `1` to not update the last read id (default: `0`)
51
+
52
+
53
+**Response**
54
+
55
+```json
56
+
57
+```
58
+
59
+
60
+## Subscriptions
61
+
62
+**Request**
63
+
64
+`ajax.php?action=subscriptions`
65
+
66
+`&showunread=` — `1` to show only unread, `0` for all subscriptions (default: `1`)
67
+
68
+
69
+**Response**
70
+
71
+```json
72
+
73
+```
74
+
75
+
76
+## Raw BBcode
77
+
78
+Fetch a post's unrendered content.
79
+
80
+
81
+**Request**
82
+
83
+`ajax.php?action=raw_bbcode`
84
+
85
+`&postid=` — post id to display (required)
86
+
87
+
88
+**Response**
89
+
90
+```json
91
+
92
+```

+ 153
- 0
docs/index.md View File

@@ -0,0 +1,153 @@
1
+The JSON API provides an easily parseable interface to BioTorrents.de.
2
+Below is the list of information available, then arguments that can be passed to it, and the format of the results.
3
+
4
+You must be logged in to use the API.
5
+This is done by sending a POST request to
6
+`https://biotorrents.de/login.php` with `username` and `password`
7
+and storing a cookie to be used to access the rest of the API.
8
+
9
+
10
+# Introduction
11
+
12
+All request URLs are in the form
13
+ajax.php?action=<action>`.
14
+
15
+All the JSON returned is in the form
16
+```json
17
+{
18
+    "status": "success",
19
+    "response": {
20
+	// data
21
+    }
22
+}
23
+```
24
+
25
+If the request is invalid, or a problem occurs, the `status` will be `failure`.
26
+In this case the value of `response` is `undefined`.
27
+
28
+
29
+# Libraries
30
+
31
+These are the current public projects listed on the
32
+[What.CD Gazelle wiki](https://github.com/WhatCD/Gazelle/wiki/JSON-API-Documentation).
33
+Questions about the API can be answered in `#development` on
34
+[Slack](https://join.slack.com/t/biotorrents/shared_invite/enQtODY2Mzg5NzI2OTk5LWQ0NmRlYzZmYTYwMzc3MjJlMzc4ZGJkNzQ1OWE4NDAxYTc3ZTdjY2NkOGRjNDA5MDAxZTA1Y2Y3M2MzMzIwZGY).
35
+
36
+Please get it touch if you'd like me to list your project below.
37
+
38
+
39
+| Language	| GitHub |
40
+| :--		| :-- |
41
+| C#		| [frankston/WhatAPI](https://github.com/frankston/WhatAPI) |
42
+| Go		| [kdvh/whatapi](https://github.com/kdvh/whatapi) |
43
+| JavaScript	| [deoxxa/whatcd](https://github.com/deoxxa/whatcd) |
44
+| Java		| [Gwindow/WhatAPI](https://github.com/Gwindow/WhatAPI) |
45
+| PHP		| [Jleagle/gazelle-api-client](https://github.com/Jleagle/gazelle-api-client) |
46
+| Python	| [isaaczafuta/whatapi](https://github.com/isaaczafuta/whatapi) |
47
+| Ruby		| [chasemgray/RubyGazelle](https://github.com/chasemgray/RubyGazelle) |
48
+
49
+
50
+# Caveats
51
+
52
+**Abusing or using this API for malicious purposes is a bannable offense and will not be taken lightly.**
53
+
54
+
55
+## Rate limit
56
+
57
+The JSON API is rate-limited to one request every ten seconds.
58
+This limit doesn't apply to the Donor class.
59
+
60
+
61
+## Under construction
62
+
63
+Some endpoints aren't working correctly right now:
64
+
65
+- artist
66
+- preview
67
+
68
+[Oppaitime Gazelle](https://git.oppaiti.me/Oppaitime/Gazelle)
69
+also contains other undocumented endpoints:
70
+
71
+- get_friends
72
+- news_ajax
73
+- send_recommendation
74
+
75
+
76
+# Not implemented
77
+
78
+## Similar artists
79
+
80
+**Request**
81
+
82
+`ajax.php?action=similar_artists`
83
+
84
+`&id=` — id of artist (required)
85
+
86
+`&limit=` — maximum number of results to return (fewer might be returned)
87
+
88
+
89
+**Response**
90
+
91
+```json
92
+
93
+```
94
+
95
+
96
+## Better
97
+
98
+Fetch various better.php info.
99
+
100
+
101
+**Request**
102
+
103
+`ajax.php?action=better`
104
+
105
+
106
+**Response**
107
+
108
+```json
109
+
110
+```
111
+
112
+
113
+
114
+## Torrent info
115
+
116
+**Request**
117
+
118
+`ajax.php?action=torrent_info`
119
+
120
+
121
+**Response**
122
+
123
+```json
124
+
125
+```
126
+
127
+
128
+## Check private
129
+
130
+**Request**
131
+
132
+`ajax.php?action=checkprivate`
133
+
134
+
135
+**Response**
136
+
137
+```json
138
+
139
+```
140
+
141
+
142
+## Vote favorite
143
+
144
+**Request**
145
+
146
+`ajax.php?action=votefavorite`
147
+
148
+
149
+**Response**
150
+
151
+```json
152
+
153
+```

+ 86
- 0
docs/meta.md View File

@@ -0,0 +1,86 @@
1
+# Meta
2
+
3
+Endpoints related to BioTorrents.de itself.
4
+
5
+
6
+## Index
7
+
8
+Fetch basic site info from the homepage,
9
+e.g., if there's a new announcement.
10
+
11
+
12
+**Request**
13
+
14
+`ajax.php?action=index`
15
+
16
+
17
+**Response**
18
+
19
+```json
20
+
21
+```
22
+
23
+
24
+## Stats
25
+
26
+Fetch the homepage sidebar info.
27
+
28
+
29
+**Request**
30
+
31
+`ajax.php?action=stats`
32
+
33
+
34
+**Response**
35
+
36
+```json
37
+
38
+```
39
+
40
+
41
+## Announcements 
42
+
43
+**Request**
44
+
45
+`ajax.php?action=announcements`
46
+
47
+
48
+**Response**
49
+
50
+```json
51
+
52
+```
53
+
54
+
55
+## Load average 
56
+
57
+**Request**
58
+
59
+`ajax.php?action=loadavg`
60
+
61
+
62
+**Response**
63
+
64
+```json
65
+
66
+```
67
+
68
+
69
+## Wiki
70
+
71
+Note that either `id` or `name` is required.
72
+
73
+**Request**
74
+
75
+`ajax.php?action=wiki`
76
+
77
+`&id=` — page id to display (required)
78
+
79
+`&name=` — page alias to display
80
+
81
+
82
+**Response**
83
+
84
+```json
85
+
86
+```

+ 50
- 0
docs/requests.md View File

@@ -0,0 +1,50 @@
1
+# Requests
2
+
3
+Endpoints related to torrent requests.
4
+
5
+
6
+## Request
7
+
8
+**Request**
9
+
10
+`ajax.php?action=request`
11
+
12
+`&id=` — request id (required)
13
+
14
+`&page=` — page of the comments to display (default: last page)
15
+
16
+
17
+**Response**
18
+
19
+```json
20
+
21
+```
22
+
23
+
24
+## Search
25
+
26
+If no arguments are specified then the most recent requests are shown.
27
+
28
+
29
+**Request**
30
+
31
+`ajax.php?action=requests`
32
+
33
+`&page=` — page to display (default: `1`)
34
+
35
+`&search=` — search term
36
+
37
+`&show_filled=` — include filled requests in results `true` or `false` (default: `false`)
38
+
39
+`&tag=` — tags to search by (comma separated)
40
+
41
+`&tags_type=` — `0` for any, `1` for match all
42
+
43
+`filter_cat[]`, `releases[]`, `bitrates[]`, `formats[]`, `media[]` — as used on requests.php
44
+
45
+
46
+**Response**
47
+
48
+```json
49
+
50
+```

+ 156
- 0
docs/torrents.md View File

@@ -0,0 +1,156 @@
1
+# Torrents
2
+
3
+Endpoints related to torrents.
4
+
5
+
6
+## Torrent
7
+
8
+**Request**
9
+
10
+`ajax.php?action=torrent`
11
+
12
+`&id=` — torrent's id (required)
13
+
14
+`&hash=` — torrent's hash (must be uppercase)
15
+
16
+
17
+**Response**
18
+
19
+```json
20
+
21
+```
22
+
23
+
24
+## Torrent group
25
+
26
+**Request**
27
+
28
+`ajax.php?action=torrentgroup`
29
+
30
+`&id=` — torrent's group id (required)
31
+
32
+`&hash=` — hash of a torrent in the torrent group (must be uppercase)
33
+
34
+
35
+**Response**
36
+
37
+```json
38
+
39
+```
40
+
41
+
42
+## Browse (search)
43
+
44
+Note that BioTorrents.de still uses Oppaitime metadata under the hood.
45
+The advanced search options are certain to change in the future.
46
+
47
+
48
+**Request**
49
+
50
+`ajax.php?action=browse`
51
+
52
+`&page=` — page to display (default: `1`)
53
+
54
+`&searchstr=` — string to search for
55
+
56
+`taglist`, `tags_type`, `order_by`, `order_way`, `filter_cat`, `freetorrent`, `vanityhouse`, `scene`, `haslog`, `releasetype`, `media`, `format`, `encoding`, `artistname`, `filelist`, `groupname`, `recordlabel`, `cataloguenumber`, `year`, `remastertitle`, `remasteryear`, `remasterrecordlabel`, `remastercataloguenumber` — as in advanced search
57
+
58
+
59
+**Response**
60
+
61
+```json
62
+
63
+```
64
+
65
+## Comments 
66
+
67
+**Request**
68
+
69
+`ajax.php?action=tcomments`
70
+
71
+`&id=` — torrent's id (required)
72
+
73
+
74
+**Response**
75
+
76
+```json
77
+
78
+```
79
+
80
+
81
+## Collage
82
+
83
+**Request**
84
+
85
+`ajax.php?action=collage`
86
+
87
+`&id=` — collage's id (required)
88
+
89
+
90
+**Response**
91
+
92
+```json
93
+
94
+```
95
+
96
+
97
+## Artist 
98
+
99
+Under construction.
100
+Currently not returning torrents.
101
+Please see the below reponse.
102
+
103
+
104
+**Request**
105
+
106
+`ajax.php?action=artist`
107
+
108
+`&id=` — artist's id (required)
109
+
110
+`&artistname=` — artist's name
111
+
112
+`&artistreleases=` — if set, only include groups where the artist is the main artist
113
+
114
+
115
+**Response**
116
+
117
+```json
118
+
119
+```
120
+
121
+
122
+## Top 10
123
+
124
+Fetch the Top 10 torrents, tags, or users.
125
+
126
+
127
+### Torrents
128
+
129
+**Request**
130
+
131
+`ajax.php?action=top10`
132
+
133
+`&limit=` — one of 10, 100, 250 (default: `10`)
134
+
135
+`&type=` — one of: torrents, tags, users (default: `torrents`)
136
+
137
+
138
+**Response**
139
+
140
+```json
141
+
142
+```
143
+
144
+
145
+### Tags
146
+
147
+```json
148
+
149
+```
150
+
151
+
152
+### Users
153
+
154
+```json
155
+
156
+```

+ 241
- 0
docs/users.md View File

@@ -0,0 +1,241 @@
1
+# Users
2
+
3
+Endpoints related to user accounts.
4
+
5
+
6
+## User
7
+
8
+If you're viewing your own account, `personal->passkey` will be shown.
9
+
10
+
11
+**Request**
12
+
13
+`ajax.php?action=user`
14
+
15
+`&id=` — id of the user to display (required)
16
+
17
+
18
+**Response**
19
+
20
+```json
21
+
22
+```
23
+
24
+
25
+## User search 
26
+
27
+**Request**
28
+
29
+`ajax.php?action=usersearch`
30
+
31
+`&search=` — the search term (required)
32
+
33
+`&page=` — page to display (default: `1`)
34
+
35
+
36
+**Response**
37
+
38
+```json
39
+
40
+```
41
+
42
+
43
+## Community stats 
44
+
45
+**Request**
46
+
47
+`ajax.php?action=community_stats`
48
+
49
+`&userid=` — id of the user to display (required)
50
+
51
+
52
+**Response**
53
+
54
+```json
55
+
56
+```
57
+
58
+
59
+## Recents (torrents)
60
+
61
+This endpoint circumvents the "upload anonymously" feature.
62
+
63
+
64
+**Request**
65
+
66
+`ajax.php?action=user_recents`
67
+
68
+`&userid=` id of user (required)
69
+
70
+`&limit=` how many recent torrents to fetch
71
+
72
+
73
+**Response**
74
+
75
+```json
76
+
77
+```
78
+
79
+
80
+## History (community)
81
+
82
+**Request**
83
+
84
+`ajax.php?action=userhistory&type=posts`
85
+
86
+`&userid=` id of user (required)
87
+
88
+
89
+**Response**
90
+
91
+```json
92
+
93
+```
94
+
95
+
96
+# Your account
97
+
98
+Endpoints that only fetch info about your own account.
99
+
100
+## Inbox
101
+
102
+**Request**
103
+
104
+`ajax.php?action=inbox`
105
+
106
+`&page=` — page number to display (default: `1`)
107
+
108
+`&search=` — filter messages by search string
109
+
110
+`&searchtype=` — one of: subject, message, user
111
+
112
+`&sort=` — if set to `unread` then unread messages come first
113
+
114
+`&type=` — one of: inbox or sentbox (default: `inbox`)
115
+
116
+
117
+**Response**
118
+
119
+```
120
+
121
+```
122
+
123
+
124
+## Conversation 
125
+
126
+**Request**
127
+
128
+`ajax.php?action=inbox&type=viewconv`
129
+
130
+`&id=` — id of the message to display (required)
131
+
132
+
133
+**Response**
134
+
135
+```json
136
+
137
+```
138
+
139
+## Bookmarks
140
+
141
+Fetch bookmarked torrents or artists.
142
+
143
+
144
+### Torrents
145
+
146
+**Request**
147
+
148
+`ajax.php?action=bookmarks`
149
+
150
+`&type=` — one of torrents, artists (default: `torrents`)
151
+
152
+
153
+**Response**
154
+
155
+```json
156
+
157
+```
158
+
159
+### Artists
160
+
161
+```json
162
+
163
+```
164
+
165
+
166
+## Notifications
167
+
168
+**Request**
169
+
170
+`ajax.php?action=notifications`
171
+
172
+`&page=` — page number to display (default: `1`)
173
+
174
+
175
+**Response**
176
+
177
+```json
178
+todo
179
+```
180
+
181
+
182
+### Get user notifications
183
+
184
+**Request**
185
+
186
+`ajax.php?action=get_user_notifications`
187
+
188
+
189
+**Response**
190
+
191
+```json
192
+todo
193
+```
194
+
195
+
196
+### Clear user notification
197
+
198
+**Request**
199
+
200
+`ajax.php?action=clear_user_notification`
201
+
202
+`&type=` — one of the below NotificationsManager class constants:
203
+
204
+- Inbox
205
+- News
206
+- Blog
207
+- StaffPM
208
+- Torrents
209
+- Quotes
210
+- Subscriptions
211
+- Collages
212
+- Global
213
+
214
+
215
+**Response**
216
+
217
+```json
218
+
219
+```
220
+
221
+
222
+## Password validate
223
+
224
+Is your current password acceptable?
225
+
226
+
227
+**Request**
228
+
229
+`ajax.php?action=password_validate`
230
+
231
+
232
+**Response**
233
+
234
+```json
235
+{
236
+    "status": "success",
237
+    "response": {
238
+        "pwValidate": "true"
239
+    }
240
+}
241
+```

+ 1
- 0
mkdocs.yml View File

@@ -0,0 +1 @@
1
+site_name: 'API ⸬ BioTorrents.de'

Loading…
Cancel
Save