Jump to content

Web API suggestions

Lord Alderaan

By Lord Alderaan
in Web API

Recommended Posts

Lord Alderaan Advanced Member

Lord Alderaan

Posted
Posted

Since µTorrent 2.1 is implementing additions to the backend API I wanted to suggest a bunch of additions and a few changes.

And I'd like to discuss these instead of outright putting them to the devs because for one I don't know the webui.zip code well enough to know if my changes are optimal to handle or cumbersome to implement. And other community project devs might have their own input on what should be exposed how. Also some might see complications for the backend.

The primary reason for my additions and changes are to allow both the webui.zip and Community Projects to gain access to more (pretty much all) information. So for now I've limited myself to additions/changes to the responses from the Web API backend (i.e. no suggestions on new actions)

The following box shows ALL the possible entities. Of course the backend will only return the entities relevant to each specific request ("build" and "time" are always be returned).

+ addition

- removed

! moved

{
    "build": BUILD NUMBER (integer),
+    "time": LOCAL TIME (integer as unix timestamp),
    "settings": [
        [
            OPTION NAME (string),
            TYPE (integer based on list),
            VALUE (string)
        ],
        ...
    ],
    "label":[
        [
            LABEL (string),
            TORRENS IN LABEL (integer)
        ],
        ...
    ],
    "torrents":[
        [
            [
                HASH (string),
                STATUS (integer as bitwise),
                NAME (string),
                SIZE (integer in bytes),
                PERCENT PROGRESS (integer in per mils),
                DOWNLOADED (integer in bytes),
                UPLOADED (integer in bytes),
                RATIO (integer in per mils),
                UPLOAD SPEED (integer in bytes per second),
                DOWNLOAD SPEED (integer in bytes per second),
                ETA (integer in seconds),
                LABEL (string),
                PEERS CONNECTED (integer),
                PEERS IN SWARM (integer),
                SEEDS CONNECTED (integer),
                SEEDS IN SWARM (integer),
                AVAILABILITY (integer in 1/65536ths),
                TORRENT QUEUE ORDER (integer),
                REMAINING (integer in bytes),
                SOURCE URL (string),
                ?? (string),
+                ADDED (integer as unix timestamp),
+                COMPLETED (integer as unix timestamp),
+                ACTIVE (integer as unix timestamp)                
            ]
        ],
        ...
    ],
    "torrentp": [idem],
    "torrentm": [idem],
    "torrentc": CACHE ID (string integer),
    "rssfeeds": [??],
    "rssfilters": [??],
-    "files":[],
-    "props":[],
    "error": DESCRIPTION (string)
+    "details" [
        [
!            "hash": HASH (string),
!            "trackers": TRACKERS (string),
!            "ulrate": UPLOAD LIMIT (integer in bytes per second),
!            "dlrate": DOWNLOAD LIMIT (integer in bytes per second),
!            "superseed": INITIAL SEEDING (integer),
!            "dht": USE DHT (integer based on list),
!            "pex": USE PEX (integer based on list),
+            "lpd": USE LPD (integer based on list),
!            "seed_override": OVERRIDE QUEUEING (integer),
!            "seed_ratio": SEED RATIO (integer in per mils),
!            "seed_time": SEEDING TIME (integer in seconds),
!            "ulslots": UPLOAD SLOTS (integer),
+            "webseeds": WEBSEEDS (string),    
+            "elapsed": ELAPSED (integer in seconds),
+            "wasted": WASTED (integer in bytes),
+            "cachepeers": PEERS IN CACHE (integer),
+            "cacheseeds": SEEDS IN CACHE (integer),
+            "saveas": SAVE AS (string),
+            "created": CREATED (integer as timestamp),
+            "createdby": CREATEDBY (string),
+            "pieces": PIECES (integer),
+            "piecesize": PIECESIZE (integer in bytes),
+            "piecehave": PIECEHAVE (integer),
+            "comment": COMMENT (string),
+            "trackerlist": [
                [
+                    NAME (string),
+                    STATUS (integer based on list),
+                    SEEDS (integer),
+                    PEERS (integer),
+                    INTERVAL (integer in seconds),
+                    MIN INTERVAL (integer in seconds),
+                    NEXT UPDATE (integer as unix timestamp),
+                    DOWNLOADED (integer)
                ],
                ...
            ],
+            "peers": [
                [
+                    IP (string),
+                    PORT (integer),
+                    CLIENT (string),
+                    FLAGS (string),
+                    PROGRESS (integer per mils),
+                    RELEVANCE (integer per mils),
+                    DOWN SPEED (integer in bytes per second),
+                    UP SPEED (integer in bytes per second),
+                    REQS (integer),
+                    WAITED (integer as unix timestamp),
+                    UPLOADED (integer in bytes),
+                    DOWNLOADED (integer in bytes),
+                    HASHERR (integer),
+                    PEER DOWNLOAD RATE (integer in bytes per second),
+                    MAX UP SPEED (integer in bytes per second),
+                    MAX DOWN SPEED (integer in bytes per second),
+                    QUEUED (integer in bytes),
+                    INACTIVE (integer as unix timestamp)
                ],
                ...
            ],            
+            "pieces": [
                [
+                    NUMBER (integer),
+                    SIZE (integer in bytes),
+                    NUMBER OF BLOCKS (integer),
+                    BLOCKS COMPLETED (integer),
+                    AVAILABILTIY (integer),
+                    PRIORITY (integer based on list),
+                    TIMEOUT (integer as timestamp),
+                    MODE (integer based on list)
                ],
                ...
            ]            
+            "files": [
                [
!                    FILE NAME (string),
!                    FILE SIZE (integer in bytes),
!                    DOWNLOADED (integer in bytes),
!                    PRIORITY (integer based on list)
+                    FULL PATH (string),
                ],
                ...
            ]
        ],
        ...
    ],
    "stats": [
+        "dlspd": GLOBAL DOWNLOAD SPEED (integer in bytes per second),
+        "ulspd": GLOBAL UPLOAD SPEED (integer in bytes per second),
+        "dlloc": LOCAL DOWNLOAD SPEED (integer in bytes per second),
+        "ulloc": LOCAL UPLOAD SPEED (integer in bytes per second),
+        "dlovr": GLOBAL DOWNLOAD OVERHEAD (integer in bytes per second),
+        "ulovr": GLOBAL UPLOAD OVERHEAD (integer in bytes per second),
+        "dlses": SESSION DOWNLOADED (integer in bytes),
+        "ulses": SESSION UPLOADED (integer in bytes),
+        "dltod": TODAY DOWNLOADED (integer in bytes),
+        "ultod": TODAY UPLOADED (integer in bytes),
+        "tf31": TRANSFERED LAST 31 DAYS (integer in bytes),
+        "dltot": TOTAL DOWNLOADED (integer in bytes),
+        "ultot": TOTAL UPLOADED (integer in bytes),
+        "runtime": TOTAL RUNNING TIME (integer in seconds),
+        "added": TORRENTS ADDED (integer),
+        "launches": PROGRAM LAUNCHED (integer),
+        "lastlaunch": LAST LAUNCH (integer as timestamp),
+        "incoming": INCOMING CONNECTIONS (integer),
+        "outgoing": OUTGOING CONNECTIONS (integer),
+        "handshake": HANDSHAKES (integer),
+        "curconn": CURRENT CONNECTIONS (integer),
+        "utp": UTP CONNECTING (integer),
+        "tcp": TCP CONNECTING (integer),
+        "halfopen": HALFOPEN (integer),
+        "diskfree": FREE DRIVE DEFAULT DOWNLOAD DIR (integer in bytes)
+        "disksize": SIZE DRIVE DEFAULT DOWNLOAD DIR (integer in bytes)
    ]
}

Add a "time" entity to all responses (like "build").

With the addition of timestamp based fields it is important to know what the current time for the µTorrent backend is. This way miscalculations due to timezones are prevented. In fact backend timestamps can be converted to frontend actual time by adding the difference between the current frontend time and the "time" entity.

ACTIVE field in torrents list as a timestamp.

The "torrents" entity uses caching. The µTorrent GUI reports the time in seconds that passed since the Last Activity. This value would change constantly for ALL torrents making caching impossible. A timestamp of the last change will remain static for torrents that are inactive/unchanged and the frontend can convert back to seconds using the new "time" entity.

Deprecate current "files" and "props" entities and move that info to a new "details" entity.

When requesting the files or properties of multiple torrents/hashes the response will end up with multiple of these entities which makes it incompatible with most JSON converters/parsers. Setting up a new "details" entity allows us to fix this issue while allowing us to remain backwards compatible*.

New "details" entity.

The details entity will iterate all requested torrents (hash=TOR1&hash=TOR2&hash=TOR3 etc). It will always show the "hash" entity. But it will only show those other entities as were requested.

So for example ?action=getfiles&hash=TOR1&hash=TOR2 will return one "details" entity which lists two torrents with only the "hash" and "files" entities of each.

The getprops action will return all the entities from "hash" till "comment" for each torrent and can be used by both the properties dialog and the general tab.

Requests

The requests would be:

[ul][li]list=1 - Returns "label", "torrent*" and "rss*"

[/li][li]action=getsettings - Returns "settings"

[/li][li]action=getprops&hash=??&hash=??... - Returns "hash" till "comment" of "details" for each hash

[/li][li]action=getfiles&hash=??&hash=??... - Returns "hash" and "files" of "details" for each hash

[/li][li]action=getpeers&hash=??&hash=??... - Returns "hash" and "peers" of "details" for each hash

[/li][li]action=getpieces&hash=??&hash=??... - Returns "hash" and "pieces" of "details" for each hash

[/li][li]action=getdetails&hash=??&hash=??... - Returns full "details" for each hash

[/li][li]action=getstats - Returns "stats"

[/li][/ul]

No auto-refresh

Since only list=1 has caching only list=1 should be requested continuously. The rest should only be requested once (i.e. in the webui.zip frontend when opening the tab or dialog in question).

To make this clear to the user the tabs in the webui.zip should have a Refresh button and/or show the age of the displayed information. For dialogs (i.e. torrent properties) this is not needed.

* For backwards compatibility I suggest sending both the "props" entity and the "details" entity when an action=getprops request comes in, same goes for getfiles. Another option is to have getprops/getfiles return the old entities and invent new actions for getting files or properties using the new "details" entity.

Related trac tickets:

#54, #62, #64, #83, #94

Link to comment
Share on other sites

Archived

This topic is now archived and is closed to further replies.

Go to topic listing
×
×
  • Create New...