-
Notifications
You must be signed in to change notification settings - Fork 6
/
API_Specs.txt
405 lines (347 loc) · 24.1 KB
/
API_Specs.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
JDownloader Premium API
1. General
1.1 Request Method
The API Uses POST HTTP Requests
1.2 Data Format
Please use JSON as response format. All Examples here use formated JSON for readability. However,you can ignore whitespace, newlines and other prettyprinting.
1.3 "Challenge" Parameter
To detect "Men in the middle", each request has to send a &challenge=<RANDOM STRING> parameter.
The response has to be surrounded by this value. A normal, "error-free" response thus looks like this:
-----------------------------------------------------------------------
|
| <challenge[String]><Response Data[JSON]><challenge[String]>
|
-----------------------------------------------------------------------
1.4 Errors
In case of Errors, the API has to return an error Object, and an ERROR marker before the json response.
-----------------------------------------------------------------------
|
| <challenge[String]>ERROR{"code":<errorcode[long]>,"msg":"<error description[String]>"}<challenge[String]>
|
-----------------------------------------------------------------------
1.5 Encoding
Please make sure that all parameters are send and handled in UTF-8 Encoding. Please assure that your API is able to handle special chars correctly
1.6 Login
Login can be done by &user and &pass parameter in each request, or by sending the &session parameter (see "getAccountDetails")
2. Commands
2.1 getAccountDetails
2.1.1 Responsedata
-----------------------------------------------------------------------
|
| {
| "type" : "Premium",
| "expireTime" : 130129841400,
| "traffic" : 36774829453,
| "autoRefill" : true,
| "concurrentDownloads" : 20,
| "maxChunks" : 10,
| "concurrentConnections" : 50,
| "resume" : true,
| "session" : "47dhd829degd9"
| }
|
-----------------------------------------------------------------------
type [String]
Free String that describes in short the accounttype (free, premium, gold, platin,...)
expireTime [long]in milliseconds
Expire Time of this account in milliseconds unixtimestamp
-1 = unlimited
traffic [long] in bytes
Free traffic available for download.
autoRefill [boolean]
True if this account autorefills without user interaction. For example if the account has a daily limit, and auto refills the next day
concurrentDownloads [long]
How many concurrent downloads can we start?
-1 = unlimited
maxChunks [long]
By loading one file with several connections, we can boost the users downloadspeed. The server has to support several connections, and http Range-Headers. We call this "chunkload"
-1 = unlimited
concurrentConnections [long]
If we use Chunkload, we have several connections per file. If there is a concurrent connection limit, please set this here.
-1 = unlimited
resume [boolean]
Is Resuming broken downloads allowed? This Feature requires Serverside enabled range Headers
session [String] OPTIONAL
To use auth protected API Features, we need to login. We use either &user and &pass parameters, or a &session parameter. If you want us to use the session parameter as often as possible, please return this parameter here. We will renew the session if we get a session invalid error.
2.1.2 Possible Errors
(Please see the Error Section to get a better description of each error)
1 user unknown
2 password wrong
3 logins wrong
4 session invalid
5 IP blocked
0 API Error
6 Custom
2.1.3 Example Request
2.1.3.1 Success
-----------------------------------------------------------------------
|
| ----------------Request------------------
| POST /api.php HTTP/1.1
| Host: yourhost.com
| Connection: close
|
| cmd=getAccountDetails&challenge=dfhsds73hf&user=testuser&pass=testpassword
| ----------------Response------------------
| HTTP/1.1 200 OK
| Connection: close
|
| dfhsds73hf{
| "type" : "Premium",
| "expireTime" : 130129841400,
| "traffic" : 36774829453,
| "autoRefill" : true,
| "concurrentDownloads" : 20,
| "maxChunks" : 10,
| "concurrentConnections" : 50,
| "resume" : true,
| "session" : "47dhd829degd9"
| }dfhsds73hf
|
-----------------------------------------------------------------------
2.1.3.2 Error
-----------------------------------------------------------------------
|
| ----------------Request------------------
| POST /api.php HTTP/1.1
| Host: yourhost.com
| Connection: close
|
| cmd=getAccountDetails&challenge=dfhsds73hf&user=testuser&pass=testpassword
| ----------------Response------------------
| HTTP/1.1 200 OK
| Connection: close
|
| dfhsds73hfERROR{
| "code" : 2,
| "msg" : "Password is wrong"
| }dfhsds73hf
|
-----------------------------------------------------------------------
2.2 getLinkStatus
2.2.1 Parameters
(This command does not require logins!)
2.2.1.1 links
A newline (\r\n) separated list of all links(linkids). We do not have to use full links here, but can use link-IDs instead.
2.2.2 Response
The response is a map. Each linkid is mapped to a statusobject
-----------------------------------------------------------------------
|
| {
| "linkid1" : {
| "status" : "online",
| "filename" : "myFile.zip",
| "filesize" : 134654654,
| "md5" : "2fcab58712467eab4004583eb8fb7f89",
| "sha1" : "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
| "custom" : "any additional fileinfos",
| "password" : "true"
| },
| "linkid2" : {
| "status" : "online",
| "filename" : "myFile2.zip",
| "filesize" : 13465454654,
| "md5" : "4004583eb2fcab58712467eab8fb7f89",
| "sha1" : "e1bb76e73912fd4e1c67a2d28fced849eb93eb12",
| "custom" : "any additional fileinfos",
| "password" : "false"
| }, …
| }
|
-----------------------------------------------------------------------
status [String] "online"|"offline"|"tempUnavailable"|"Invalid"
Possible values:
online File is online and can be downloaded
offline File is offline, and cannot be downloaded any more
tempUnavailable File is online, but not available atm.
Invalid LinkID is not valid.
filename [String]
Full filename of this file
filesize [long] in bytes
Exact filesize
md5 [String] OPTIONAL
Md5 checksum of this file. We use this to find download errors
sha1 [String] OPTIONAL
Alternative to MD5
custom [String] OPTIONAL
If you have any further information about this file, let us know here.
Password [String] null|"true"|"false" OPTIONAL
If downloading this file is password protected, set this to "true", else to "false"
2.2.3 Possible Errors
13 – Invalid Links
2.2.4 Example Request
2.2.4.1 Success
-----------------------------------------------------------------------
|
| ----------------Request------------------
| POST /api.php HTTP/1.1
| Host: yourhost.com
| Connection: close
|
| cmd=getLinkStatus&challenge=dfhsds73hf&user=testuser&pass=testpassword&links=http://yourhost.com/file/123432
| http://yourhost.com/file/123433
| http://yourhost.com/file/123434
|
| ----------------Response------------------
| HTTP/1.1 200 OK
| Connection: close
|
| dfhsds73hf{
| "http://yourhost.com/file/123432" : {
| "status" : "online",
| "filename" : "myFile2.zip",
| "filesize" : 13465454654,
| "md5" : "4004583eb2fcab58712467eab8fb7f89",
| "sha1" : "e1bb76e73912fd4e1c67a2d28fced849eb93eb12",
| "custom" : "any additional fileinfos",
| "password" : "false"
| }
| "http://yourhost.com/file/123433" : {
| "status" : "offline"
| }
| "http://yourhost.com/file/123434" : {
| "status" : "offline",
| "filename" : "myFile3.zip",
| "filesize" : 13465454654,
| "md5" : "400eb2fcab58712467eab45838fb7f89",
| "sha1" : "6e73912fd4e1c67a2d28fced849eb93ee1bb7b12",
| "custom" : "any additional fileinfos",
| "password" : "false"
| }
| }dfhsds73hf
|
-----------------------------------------------------------------------
2.2.4.2 Error
-----------------------------------------------------------------------
|
| ----------------Request------------------
| POST /api.php HTTP/1.1
| Host: yourhost.com
| Connection: close
|
| cmd=getLinkStatus&challenge=dfhsds73hf&user=testuser&pass=testpassword&links=http://yourhost.com/file/123432
| http://yourhost.com/file/123433
| http://yourhost.com/file/123434
|
| ----------------Response------------------
| HTTP/1.1 200 OK
| Connection: close
|
| dfhsds73hfERROR{
| "code" : 13,
| "msg" : "Invalid File Id(s)"
| }dfhsds73hf
|
-----------------------------------------------------------------------
2.3 download
2.3.1 Parameters
2.3.1.1 downloadPass OPTIONAL
If the download is passwordprotected
2.3.1.2 linkid
Same linkid we use for linkcheck. This can be the whole http link, or only a part of it.
2.3.2 Response
In errorcase, please do NOT send Content-Disposition, but a normal error response.
If everything is fine, we get the filedata as response. Please send these headers
2.3.2.1 Content-Disposition
see RFC2231, http://greenbytes.de/tech/tc2231/
Content-Disposition: attachment; filename*=UTF-8''test.html
2.3.2.2 Content-Length
Exact size of the file in bytes
Content-Length: 35678463
2.3.2.3 Content-MD5 (Optional)
Md5 checksum of this file. We use this to find download errors
Content-MD5: 4004583eb2fcab58712467eab8fb7f89
2.3.2.4 Content-SHA1 (Optional)
Alternative to MD5 Header
Content-SHA1: e1bb76e73912fd4e1c67a2d28fced849eb93eb12
2.3.3 Possible Errors
0 API Error
1 user unknown
2 password wrong
3 logins wrong
4 session invalid
5 IP blocked
6 Custom
7 Download Password wrong
8 Traffic limit reached
9 account type invalid
10 link offline
11 link temp unavailable
12 connection limit reached
2.3.4 Example Request
2.3.4.1 Success
-----------------------------------------------------------------------
|
| ----------------Request------------------
| POST /api.php HTTP/1.1
| Host: yourhost.com
| Connection: close
|
| cmd=download&challenge=dfhsds73hf&user=testuser&pass=testpassword&linkid=http://yourhost.com/file/123432
|
|
| ----------------Response------------------
| HTTP/1.1 200 OK
| Content-Disposition: attachment; filename*=UTF-8''<file name.zip>
| Content-Length: 35678463
| Content-MD5: 4004583eb2fcab58712467eab8fb7f89
| Connection: close
|
| ...<data 35678463 bytes>...
|
-----------------------------------------------------------------------
2.3.4.2 Error
-----------------------------------------------------------------------
|
| ----------------Request------------------
| POST /api.php HTTP/1.1
| Host: yourhost.com
| Connection: close
|
| cmd=download&challenge=dfhsds73hf&user=testuser&pass=testpassword&linkid=http://yourhost.com/file/123432
|
| ----------------Response------------------
| HTTP/1.1 200 OK
| Connection: close
|
| dfhsds73hfERROR{
| "code" : 8,
| "msg" : "Traffic Limit reached. Try again in 3 hours"
| }dfhsds73hf
|
-----------------------------------------------------------------------
3. Errors
-----------------------------------------------------------------------
| {
| "code" : 5
| "msg" : "IP Blocked. To many failed logins!"
| }
-----------------------------------------------------------------------
Code 0 Technical API Error
If we use wrong parameters, or any other technical error occures
Code 1 User Unknown
Login Error: The user is unknown
Code 2 Password wrong
Login Error: The user is known, but password is wrong
Code 3 Logins wrong
If you cannot differ between 1 and 2, use this code
Code 4 Session Invalid
Login Error: The given Session is invalid. We will try to get a new one
Code 5 IP Blocked
If you want to prevent hacking attemps, you can block the user's ip if he does too many wrong requests. If you do this, please provide an option to unblock the user. For example by solving a captcha request.
Code 6 Custom
For errors not matching the other codes. Please provide a description in the error msg
Code 7 Download password wrong
If download is password protected, and we have no, or a wrong password parameter
Code 8 traffic limit reached
Cannot download because the users traffic limit is reached
Code 9 account type not supported
For example if a user tries to download a file which cannot be downloaded with his accounttype
Code 10 link offline
Link is offline and cannot be downloaded (see link status)
Code 11 link temp. Unavailable
Link cannot be downloaded right now. (see link status)
Code 12 Connection Limit
Cannot download, because user reached his connection limit
Code 13 Invalid Links
Linkcheck failed, because there is one or more invalid links in the given list. Please avoid throwing this error. However some hosters want to avoid brutforce linkgrabbing, and this let the whole request fail of at least one invalid link is in the list.