2011-03-28 09:02:18 +00:00
JDownloader Premium API
2014-05-07 18:10:55 +00:00
2011-03-28 09:16:31 +00:00
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:
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
-----------------------------------------------------------------------
|
| <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.
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
-----------------------------------------------------------------------
|
| <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
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
1.6 Login
Login can be done by &user and &pass parameter in each request, or by sending the &session parameter (see "getAccountDetails")
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
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.
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
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
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
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
|
-----------------------------------------------------------------------
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
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.
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
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"
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
2.2.3 Possible Errors
13 –
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
2.2.4 Example Request
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
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
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
2.3.4 Example Request
2.3.4.1 Success
2011-03-28 09:06:14 +00:00
2011-03-28 09:16:31 +00:00
-----------------------------------------------------------------------
|
| ----------------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
|
-----------------------------------------------------------------------
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
3. Errors
2011-03-28 09:06:14 +00:00
-----------------------------------------------------------------------
2011-03-28 09:16:31 +00:00
| {
| "code" : 5
| "msg" : "IP Blocked. To many failed logins!"
| }
2011-03-28 09:06:14 +00:00
-----------------------------------------------------------------------
2011-03-28 09:16:31 +00:00
Code 0 Technical API Error
If we use wrong parameters, or any other technical error occures
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
Code 1 User Unknown
Login Error: The user is unknown
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
Code 2 Password wrong
Login Error: The user is known, but password is wrong
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
Code 3 Logins wrong
If you cannot differ between 1 and 2, use this code
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
Code 4 Session Invalid
Login Error: The given Session is invalid. We will try to get a new one
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
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.
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
Code 6 Custom
For errors not matching the other codes. Please provide a description in the error msg
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
Code 7 Download password wrong
If download is password protected, and we have no, or a wrong password parameter
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
Code 8 traffic limit reached
Cannot download because the users traffic limit is reached
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
Code 9 account type not supported
For example if a user tries to download a file which cannot be downloaded with his accounttype
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
Code 10 link offline
Link is offline and cannot be downloaded (see link status)
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
Code 11 link temp. Unavailable
Link cannot be downloaded right now. (see link status)
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
Code 12 Connection Limit
Cannot download, because user reached his connection limit
2011-03-28 09:02:18 +00:00
2011-03-28 09:16:31 +00:00
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.
2011-03-28 09:02:18 +00:00
