network api documentation - nzbvortex · 2013-01-27 · pauseall and resumeall deprecated 2 2.8.3...

NZBVortex Network APIdocumentation

Revision Description API level NZBVortex version

1.0 Initial document version 1 2.8.0

1.1 Fixed URL’s and added Web chapter 1 2.8.0

1.2 Fixed authentication base64 details, improved API documentation.

1 2.8.0

1.3 Improved network API, new API levelBASE64 padding support authenticationpauseAll and resumeAll deprecated

2 2.8.3

1.4 Added NZB move API call documentation 2 2.8.3

1.5 New functions added, some functions don’t need authentication anymore

2.1 2.8.5

1.6 Added authentication exampleApi 2.2: specify download name and group name during add of NZB

2.2 2.9.0

...........................................................................................1. Introduction! 5....................................................................................................................................................Basics! 5

........................................................................................................................................Authentication! 5

.................................................................................................................................JSON and JSONP! 7

................................................................................................WebUI source files / Your help wanted!! 8

...........................................................................................................................Request API functions! 8

.......................................................................................2. Authentication! 9......................................................................................................................Get authentication nonce! 9

........................................................................................................................Login / Get Session ID! 10

......................................................................................3. App functions! 11.................................................................................................................................Current API level! 11

..............................................................................................................................Application version! 12

...............................................................................................................Get current download speed! 12

...............................................................................................................WebUpdate (compiled stats)! 13

.....................................................................................4. NZB functions! 14............................................................................................................................Get all NZBs details! 14

...........................................................................................................Get a details of a specific NZB ! 15

..........................................................................................................Add NZB via HTTP File Upload! 16

............................................................................................................................Add a NZB via URL! 17

......................................................................................................................................Pause a NZB ! 18

...................................................................................................................................Resume a NZB ! 18

.....................................................................................................................................Cancel a NZB ! 19

......................................................................................................................................Delete a NZB ! 19

...................................................................................................................................Pause all NZBs! 20

........................................................................................................Pause all NZBs (DEPRECATED)! 20

................................................................................................................................Resume all NZBs! 21

....................................................................................................Resume all NZBs (DEPRECATED)! 21

..................................................................................................................................Cancel all NZBs! 22

...................................................................................................................................Delete all NZBs! 22

........................................................................................................Clear finished NZBs from Queue! 23

......................................................................................................Move NZB up one place in queue! 24

..................................................................................................Move NZB down one place in queue! 24

..................................................................................................................Move NZB to top of queue! 25

............................................................................................................Move NZB to bottom of queue! 25

......................................................................................Download NZB next (move to second place)! 26

.................................................................................................Move NZB to specific index in queue! 26

.............................................................................................Speed Limit! 27.............................................................................................................Get current Speed Limit state ! 27

.............................................................................................................................Enable Speed Limit! 28

............................................................................................................................Disable Speed Limit! 29

................................................................................6. Sleep when done! 30.....................................................................................................Get current sleep when done state! 30

....................................................................................................................Enable sleep when done! 31

....................................................................................................................Disable sleep when done! 32

.....................................................................................................7. Files ! 33.............................................................................................................................Get files for NZB id! 33

...................................................................................................8. States ! 34..........................................................................................................................................NZB states! 34

............................................................................................................................................File states! 35

1. IntroductionBasicsNZBVortex Network API uses a REST like API using normal GET and POST HTTP operations for API calls which returns JSON. The communication will take place using HTTPS.

We are aware that the current default installation will use a self-signed certificate for HTTPS. This is less optimal at best. This setup is chosen because of end-users costs and easy setup.

The API is protected by a so called API key. This API key is a pre-shared secret key which is configured in NZBVortex. Clients and / or users should configure or enter this pre-shared secret API key in the client so it is able to communicate with NZBVortex’s API.

The API Key is never transmitted to NZBVortex, instead the client will calculate a SHA256 hash and send it to the server. The server is able to verify the hash and accept a session for this client.

AuthenticationAuthentication is relatively simple: firstly the client must request for an auth nonce from the server. This auth nonce is valid for 30 seconds. Secondly the client must generate it’s own client nonce (random for every authentication!). Thirdly the client will send the server nonce, the client nonce and the base64 of the SHA265 hash of both nonces and and the API Key and send it to the server. The server nonce, client nonce and base64 hash are separated by a colon.

Login request sends:• Server nonce• Client nonce• BASE64(SHA256(server_nonce:client_nonce:apikey))

Note 1: do not use BASE64 padding characters (=) for API level 1 authentication, BASE64 padding characters support is added in API level 2.

Note 2: BASE64 encoding in performed on the raw SHA256 hash bytes, not hex string!

If the authentication is verified and is valid the server will return a session id which is used for all subsequent calls to the server to identify the client. The session id will be invalidated after 5 minutes of inactivity.

Test your hash calculation routine with the following data.

Use the following data to check your hash routine

Nonce:! ! B8DB315C-2C2C-45AA-9088-875D9ED9A90EClient nonce:!! 5E992A86ApiKey:! ! 1EC2-FCD9

Step A: compile the string to be hashesCompiled pre-hash string.Pseudocode: string = NONCE:CNONE:APIKEYResult: B8DB315C-2C2C-45AA-9088-875D9ED9A90E:5E992A86:1EC2-FCD9

Step B: SHA256 the compiled stringPseudocode: SHA256(STEP_A)Result: 026153af2bfec80490ea36a941fe0a803f4286f265ebbf9ee52cad16109b5913

Step C: Base64 encode the bytes of SHA256 hashImportant: calculate the base64 on the bytes of BASE64, not the hex string.Pseudocode: BASE64(SHA256(STEP_A))Result: AmFTryv+yASQ6japQf4KgD9ChvJl67+e5SytFhCbWRM=

Manually cross check your functionalityKeep in mind; below tools use HEX string instead of bytes purely for demonstration.The resulting hash is correct and same as NZBVortex would get the BASE64 hash.

Step A: SHA256 from your compiled string (results HEX string)http://www.xorbin.com/tools/sha256-hash-calculator

Step B: Base64 from bytes in HEX stringThis in essence decodes the HEX strint to bytes and then does the BASE64 encode.http://tomeko.net/online_tools/hex_to_base64.php

http://www.xorbin.com/tools/sha256-hash-calculator

http://www.xorbin.com/tools/sha256-hash-calculator

http://tomeko.net/online_tools/hex_to_base64.php

http://tomeko.net/online_tools/hex_to_base64.php

JSON and JSONPWe are aware that websites hosted on other domains are not allowed to make AJAX calls to a different domain for security reasons. Because of this NZBVortex does support both normal JSON and JSONP API calls. JSONP will allow sites hosts on different domains to AJAX REST calls to NZBVortex. To enable JSONP calls use i.e. JQuery’s JSONP. Make sure to specify the “&callback=yourfunction” URL parameter during the REST JSONP requests.

Because JSONP does use a “javascript include” hack to get the JSON results from another server the HTTP status codes are not accessible anymore; because of this NZBVortex will store the HTTP status codes in the JSON results itself. Please inspect the httpStatusCode key in the JSON result.

WebUI source files / Your help wanted!The Web UI is a 100% client side web application. A combination of HTML, CSS and Javascript. The UI is Javascript drive and manipulated via the DOM. The Web UI is published without any licensing and is public domain. We really would like other developers to make changes and improve the Web UI and we’d like to receive back any patches so our customers can use your improvements as well!

We really like to incorporate any improvements you make to the Web UI.

The Web files can be found in the following folders (including the ~)Open Finder, press CMD-Shift-G and copy past the below folder and press enter.

Version of NZBVortex Folder

Downloaded via the site ~/Library/Application Support/NZBVortex/WebUI/

Downloaded via Mac App Store ~/Library/Containers/com.NZBVortex.NZBVortex/Data/Library/Application Support/NZBVortex/WebUI/

Request API functionsThe API doesn’t fully cover all functionality of NZBVortex. Please do not hesitate to contact us if we can add a function to the API which will make your product even more awesome.

Please contact us at [email protected] and request what function you would like to get added to NZBVortex!

mailto:[email protected]

mailto:[email protected]

2. AuthenticationGet authentication nonceDescription

GET Request URL

Parameters

Example

API level

Needs Authentication

HTTP result codes

Result

Get authentication Nonce used for LoginNonce is valid for 30 seconds

/api/auth/nonce

None

/api/auth/nonce

Introduced in API level 1

No

200 - Operation okay

{! “authNonce” : “(generated_nonce)”}

Login / Get Session IDDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Login / get Session ID

Login to the server by validating client using a pre-shared API key. The API key is configured in NZBVortex. The API key is not send in plaintext but as a BASE64 encoded SHA256 hash of: the server nonce (NONCE), the client nonce (CNONCE) and the API key separated by semicolons.

Note 1: do not use BASE64 padding characters (=) for API level 1 authentication, BASE64 padding characters support is added in API level 2.

Note 2: BASE64 encoding in performed on the raw SHA256 hash bytes, not hex string!

Session ID will be invalidated after 5 minutes idle time.

/api/auth/login

nonce! ! = server nonce (retrieved via /api/auth/nonce)cnonce!! = client generated nonce (random per authentication)hash! ! = BASE64(SHA256(nonce:cnonce:apikey))

/api/auth/login?nonce=XX&cnonce=YY&hash=ZZ


No


{! “sessionID” : “(generated_id)”,! “loginResult” : “successful”}

{! “loginResult” : “failed”}

3. App functionsCurrent API levelDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Get current API level

Please use this function to check if your application is compatible with NetworkAPI functions. Do not use application version!

Please note: the format is a string with the following format“MAJOR.MINOR” for example: “2.1”

Breaking API changes increases the MAJOR version.New functions, bugfixes only increase MINOR.

When MAJOR remains the same the API is guaranteed to remain compatible.

/api/app/apilevel

/api/app/apilevel


Api-level 1 and 2: ! ! YesApi-level 2.1 and newer: ! No

200 - Operation okay403 - Authentication failed or expired; login again

{! “result” : “ok”,! “apilevel” : “2.1”}

{! “result” : “not_logged_in”}

Application versionDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Get current application version.

Do not use this version to check for compatibility. use apilevel instead!

/api/app/appversion

/api/app/appversion

Introduced in API level 2.1

No


{! “result” : “ok”,! “appversion” : “2.9.0”}


Get current download speedDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Return the current download speed in bytes per second

/api/app/downloadspeed

sessionid! = Authentication Session ID

/api/app/downloadspeed?sessionid=SID


Yes


{! “result” : “ok”,! “speed” : 500}


WebUpdate (compiled stats)Description

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

This API call will collect and return the results of /app/downloadspeed, /speedlimit, /sleepwhendone and /file/(nzbid)

It’s a one-HTTP operation get all status call. For optimal web update experience. Optimization API call.

nzbid is optional.(/app/webUpdate gets all info except files)

/api/app/(nzbid)/webUpdate


/api/app/(nzbid)/webUpdate?sessionid=SID


Yes


{! “result” : “ok”,! “speed” : 500,! “speedlimit_enabled” : false,! “speedlimit” : 500,! “speedlimit_minutes” : 10,! “sleepwhendone” : false,! “files” : [ { file1 }, { file2 } ]}


4. NZB functionsGet all NZBs detailsDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Get overview of all NZBs currently in the queue

/api/nzb


/api/nzb?sessionid=SID


Yes


{! “result” : “ok”,! “nzbs” : [! ! {! ! ! "id" : 1,! ! ! "uiTitle" : "Display title",! ! ! "destinationPath" : "/Download/Path",! ! ! "nzbFileName" : "/Downloads/some.nzb",! ! ! "isPaused" : (0|1), (true or false)! ! ! "state" : 1, (see state section)! ! ! "statusText": "paused by user"! ! ! "transferedSpeed" : 512, (speed in bytes/s)! ! ! "progress" : 49.5, (progress in float)! ! ! "downloadedSize" : 512, (downloaded bytes)! ! ! "totalDownloadSize" : 1024, (total download size)! ! ! "postDate" : 1347130720, (nil or sec since 1970)! ! ! "totalArticleCount" : 500, (total number of articles)! ! ! "failedArticleCount" : 0, (failed number of articles)! ! ! "groupUUID" : "{GUID}" (download group)! ! },

! ! ! ! {! ! ! (....)! ! }! ]}

Get a details of a specific NZBDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Get a specific NZB from the queueReplace (nzbid) with NZB id.

/api/nzb/(nzbid)


/api/nzb/1?sessionid=SID


Yes


{! “result” : “ok”,! “nzbs” : [! ! {! ! ! "id" : 1,! ! ! "uiTitle" : "Display title",! ! ! "destinationPath" : "/Download/Path",! ! ! "nzbFileName" : "/Downloads/some.nzb",! ! ! "isPaused" : (0|1), (true or false)! ! ! "state" : 1, (see state section)! ! ! "statusText": "paused by user"! ! ! "transferedSpeed" : 512, (speed in bytes/s)! ! ! "progress" : 49.5, (progress in float)! ! ! "downloadedSize" : 512, (downloaded bytes)! ! ! "totalDownloadSize" : 1024, (total download size)! ! ! "postDate" : 1347130720, (nil or sec since 1970)! ! ! "totalArticleCount" : 500, (total number of articles)! ! ! "failedArticleCount" : 0, (failed number of articles)! ! ! "groupUUID" : "{GUID}" (download group)! ! }! ]}


Add NZB via HTTP File UploadDescription

POST Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Add a new download to the queue.

Using a Multi-part form data file upload POST.A “ok” results just mentions the files where queued for being added to the queue not actually added to queue.

/api/nzb/add


Added in API level 2.2name! ! = Set name for download (visible in UI)groupname = Add download to group with name (optional)

/api/nzb/add?sessionid=SID&groupname=Some%20group


Yes


{! “result” : “ok”}


Add a NZB via URLDescription

POST Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Add a new download to the queue.

Using a URL parameter

/api/nzb/add

sessionid! = Authentication Session IDurl! ! = URL encoded URL (http)

Added in API level 2.2name! ! = Set name for download (visible in UI)groupname = Add download to group with name (optional)

/api/nzb/add?sessionid=SID&url=http%3A%2F%2Fwww.google.com%2Fdownload.nzb&groupname=Some%20group


Yes




Pause a NZBDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Pause NZB using NZB idReplace (nzbid) with NZB id.

/api/nzb/(nzbid)/pause


/api/nzb/1/pause?sessionid=SID


Yes




Resume a NZBDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Resume NZB using NZB idReplace (nzbid) with NZB id.

/api/nzb/(id)/resume


/api/nzb/1/resume?sessionid=SID


Yes




Cancel a NZBDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Remove a (finished/unfinished) NZB from queue, do not delete files.Replace (nzbid) with NZB id.

/api/nzb/(nzbid)/cancel


/api/nzb/1/cancel?sessionid=SID


Yes




Delete a NZBDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Remove a (finished/unfinished) NZB from queue and delete files.Replace (nzbid) with NZB id.

/api/nzb/(nzbid)/cancelDelete


/api/nzb/1/cancelDelete?sessionid=SID


Yes




Pause all NZBsDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Pause all NZBs

/api/nzb/pause


/api/nzb/pause?sessionid=SID


Yes




Pause all NZBs (DEPRECATED)Description

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Pause all NZBs (DEPRECATED)

/api/nzb/pauseAll


/api/nzb/pauseAll?sessionid=SID

Introduced in API level 1Deprecated in API level 2

Yes




Resume all NZBsDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Resume all NZBs

/api/nzb/resume


/api/nzb/resume?sessionid=SID


Yes




Resume all NZBs (DEPRECATED)Description

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Resume all NZBs (DEPRECATED)

/api/nzb/resumeAll


/api/nzb/resumeAll?sessionid=SID

Introduced in API level 1Deprecated in API level 2

Yes




Cancel all NZBsDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Remove all (finished/unfinished) NZB from queue, do not delete files.

/api/nzb/cancel


/api/nzb/cancel?sessionid=SID


Yes




Delete all NZBsDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Remove all (finished/unfinished) NZBs from queue and delete files.

/api/nzb/cancelDelete


/api/nzb/cancelDelete?sessionid=SID


Yes




Clear finished NZBs from QueueDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Clear all successfully finished download from the queue

/api/nzb/clearFinished


/api/nzb/clearFinished?sessionid=SID


Yes




Move NZB up one place in queueDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Move up NZB once place

/api/nzb/(nzbid)/moveup


/api/nzb/(nzbid)/moveup?sessionid=SID


Yes




Move NZB down one place in queueDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Move down NZB once place

/api/nzb/(nzbid)/movedown


/api/nzb/(nzbid)/moveup?sessionid=SID


Yes




Move NZB to top of queueDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Move NZB to top of queue

/api/nzb/(nzbid)/movetop


/api/nzb/(nzbid)/movetop?sessionid=SID


Yes




Move NZB to bottom of queueDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Move NZB to bottom of queue

/api/nzb/(nzbid)/movebottom


/api/nzb/(nzbid)/movebottom?sessionid=SID


Yes




Download NZB next (move to second place)Description

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Move NZB to second place in queue (download next)

/api/nzb/(nzbid)/downloadnext


/api/nzb/(nzbid)/downloadnext?sessionid=SID


Yes




Move NZB to specific index in queueDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Move an NZB to a specific index (location) in the queue.The index is zero based (first item is index 0).

The NZB will be moved before the NZB currently at the specified index.

To move the NZB at the end of queue set it to max index + 1

/api/nzb/(nzbid)/moveToIndex?index=(index in queue)&sessionid=SID

sessionid! = Authentication Session IDindex! ! = Index in queue (0 based)

/api/nzb/(nzbid)/moveToIndex?index=0?sessionid=SID

Introduced in API level 2.1

Yes




5. Speed LimitGet current Speed Limit stateDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Get current speed limit status

/api/speedlimit


/api/speedlimit?sessionid=SID


Yes


{! “result” : “ok”,! "speedlimit_enabled” : 0,! “speedlimit” : 512, (kb/s)! “speedlimit_minutes” : 10}


Enable Speed LimitDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Enable speed limit

/api/speedlimit/enable

sessionid! = Authentication Session IDspeed! ! = Speed in KB/sminutes!! = Auto disable limit after these minutes (optional)

/api/speedlimit/enable?sessionid=SID&speed=512&minutes=10


Yes




Disable Speed LimitDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Disable speed limit

/api/speedlimit/disable


/api/speedlimit/disable?sessionid=SID


Yes




6. Sleep when doneGet current sleep when done stateDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Get current Sleep when done state

/api/sleepwhendone


/api/sleepwhendone?sessionid=SID


Yes


{! “result” : “ok”,! "sleepwhendone” : true}


Enable sleep when done

Description

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Enable Sleep When done

/api/sleepwhendone/enable


/api/sleepwhendone/enable?sessionid=SID


Yes


{! “result” : “ok”,! "sleepwhendone” : true}


Disable sleep when done

Description

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Disable Sleep When Done

/api/sleepwhendone/disable


/api/sleepwhendone/disable?sessionid=SID


Yes


{! “result” : “ok”,! "sleepwhendone” : false}


7. FilesGet files for NZB idDescription

GET Request URL

Parameters

Example

API level


HTTP result codes

Result success

Result failed

Get all files for a specific NZBReplace (nzbid) with NZB id.

/api/file/(nzbid)


/api/file/1?sessionid=SID


Yes


{! “result” : “ok”,! “files” : [! ! {! ! ! "id" : 1,! ! ! "fileName" : "SomeFileName.rar"! ! ! "state" : 1,! ! ! "fileSize" : 1024,! ! ! "downloadedSize" : 900,! ! ! "totalDownloadSize" : 1250,! ! ! "extractPasswordRequired" : 0,! ! ! "extractPassword" : null,! ! ! "postDate" : 1347130720 or null,! ! ! "crc32CheckFailed" : 0! ! },

! ! { file2 }! ]}


8. StatesNZB states

State Description

0 Waiting

1 Downloading

2 Waiting for save

3 Saving

4 Saved

5 Password request

6 Queued for processing

7 User wait for processing

8 Checking

9 Repairing

10 Joining

11 Wait for further processing

12 Joining

13 Wait for uncompress

14 Uncompressing

15 Wait for cleanup

16 Cleaning up

17 Cleaned up

18 Moving to completed

19 Move completed

20 Done

21 Uncompress failed

22 Check failed, data corrupt

23 Move failed

24 Badly encoded download (uuencoded)

File statesState Description

0 Waiting

1 Downloading

2 Downloaded

3 Saving

4 Saved

5 Skipped

network api documentation - nzbvortex · 2013-01-27 · pauseall and resumeall deprecated 2 2.8.3...

Documents