mirror of
https://github.com/mirror/jdownloader.git
synced 2024-10-07 00:53:37 +00:00
406 lines
24 KiB
Plaintext
406 lines
24 KiB
Plaintext
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.
|
||
|
||
|