Transcription
Synology Download StationOfficial APISynology Download Station Official API 20140326
States and other countries.Synology Inc. 2014 Synology Inc.All rights reserved.No part of this publication maybe reproduced, stored in aretrieval system, ortransmitted, in any form or byany means, mechanical,electronic, photocopying,recording, or otherwise,without prior written permissionof Synology Inc., with thefollowing exceptions: Anyperson is hereby authorized tostore documentation on asingle computer for personaluse only and to print copies ofdocumentation for personaluse provided that thedocumentation containsSynology’s copyright notice.The Synology logo is atrademark of Synology Inc.No licenses, express orimplied, are granted withrespect to any of thetechnology described in thisdocument. Synology retains allintellectual property rightsassociated with the technologydescribed in this document.This document is intended toassist application developersto develop applications only forSynology-labeled computers.Every effort has been made toensure that the information inthis document is accurate.Synology is not responsible fortypographical errors.Synology Inc.3F-3, No. 106, Chang-An W.Rd. Taipei 103, TaiwanSynology and the Synologylogo are trademarks ofSynology Inc., registered in theUnited States and othercountries.Marvell is registeredtrademarks of MarvellSemiconductor, Inc. or itssubsidiaries in the UnitedStates and other countries.Freescale is registeredtrademarks of FreescaleSemiconductor, Inc. or itssubsidiaries in the UnitedOther products and companynames mentioned herein aretrademarks of their respectiveholders.Even though Synology hasreviewed this document,SYNOLOGY MAKES NOWARRANTY ORREPRESENTATION, EITHEREXPRESS OR IMPLIED,WITH RESPECT TO THISDOCUMENT, ITS QUALITY,ACCURACY,MERCHANTABILITY, ORFITNESS FOR APARTICULAR PURPOSE. ASA RESULT, THIS DOCUMENTIS PROVIDED “AS IS,” ANDYOU, THE READER, AREASSUMING THE ENTIRERISK AS TO ITS QUALITYAND ACCURACY. IN NOEVENT WILL SYNOLOGY BELIABLE FOR DIRECT,INDIRECT, SPECIAL,INCIDENTAL, ORCONSEQUENTIALDAMAGES RESULTINGFROM ANY DEFECT ORINACCURACY IN THISDOCUMENT, even if advisedof the possibility of suchdamages.THE WARRANTY ANDREMEDIES SET FORTHABOVE ARE EXCLUSIVEAND IN LIEU OF ALLOTHERS, ORAL ORWRITTEN, EXPRESS ORIMPLIED. No Synology dealer,agent, or employee isauthorized to make anymodification, extension, oraddition to this warranty.Some states do not allow theexclusion or limitation ofimplied warranties or liabilityfor incidental or consequentialdamages, so the abovelimitation or exclusion may notapply to you. This warrantygives you specific legal rights,and you may also have otherrights which vary from state tostate.
Table of ContentsChapter 1: IntroductionChapter 2: Get StartedAPI Workflow . 5Making Requests . 6Parsing Response . 7Common Error Code . 8Working Example. 8Chapter 3: Base APIAPI List . 12SYNO.API.Info . 12SYNO.API.Auth . 14Chapter 4: Download Station APIAPI List . 16SYNO.DownloadStation.Info . 17SYNO.DownloadStation.Schedule . 20SYNO.DownloadStation.Task . 21SYNO.DownloadStation.Statistic. 31SYNO.DownloadStation.RSS.Site . 32SYNO.DownloadStation.RSS.Feed . 34SYNO.DownloadStation.BTSearch . 36Appendix A: Download Task StatusAppendix B: Values for Details of Erroneous Tasks3Copyright Synology Inc. All Rights Reserved.
ChapterChapter 1:1IntroductionWelcome to the developer documentation for Synology’s Download Station APIs. This officialdeveloper’s guide allows you to build upon and extend your applications based on the APIs ofDownload Station, one of the most popular packages on Synology DiskStation, and interact withDownload Station via HTTP request and response.This document introduces the structure of Download Station APIs and details of API specifications.“Chapter 2: Get Started” describes the basic guidelines on how to use the APIs, which is suggested toread through before you jump right into the API spec. “Chapter 3: Base API” and “Chapter 4:Download Station API” list all available APIs and its detailed information.4Copyright Synology Inc. All Rights Reserved.
ChapterChapter 2:2Get StartedBefore making use of Download Station APIs to develop your own applications, you need to havebasic understanding of API concepts and API procedures.This chapter explains how to execute and complete API process with five sections as follows whoseexplicit explanations are provided in order: API Workflow: Briefly introduces how to work with Download Station APIs. Making Requests: Elaborates how to construct API requests. Parsing Response: Describes how to parse response data. Common Error Code: Lists all common error codes that might be returned from all DownloadStation APIs. Working Example: Provides an example from a login session to request download taskinformation.API WorkflowThe following introduces the four-step easy-to-follow workflow which guides you through theprocedures of how to make your application interact with the Download Station APIs. The workflow isillustrated as a diagram bellow.Step 1: Get API InformationFirst of all, your application needs to get API information from the target DiskStation to know whichAPIs are available for use on the target DiskStation. This information can be accessed simply througha request to query.cgi from the SYNO.API.Info API. The information provided in the response contains5Copyright Synology Inc. All Rights Reserved.
available API name, API cgi path and the API version information. Once you have all the informationat hand, your application can make further requests to all available APIs.Step 2: Session LoginIn order to make your application interact with Download Station, the application needs to log in asession with a DSM account and password. The login process is simply making a request to theSYNO.API.Auth API.Step 3: Download API RequestsOnce the account is successfully logged in, the application can start to make requests to all availableDownload APIs. In the next section “Making Requests”, instructions on how to form a valid APIrequest and how to decode response information will be given.Step 4: Session LogoutAfter finished with the steps above, the application can end the working session by making anotherrequest to SYNO.API.Auth API with the logout method.Making RequestsThere are five basic elements for constructing a valid request to any of the APIs. API name: Name of the API requested version: Version of the API requested path: cgi path of the API. The path information can be retrieved by requesting SYNO.API.Info method: Method requested sid: Authorized session ID. Each API request should pass a sid value via either HTTPGET/POST “ sid” argument or “id” value in cookie.and the syntax for the request is:GET/webapi/ CGI PATH ?api API NAME &version VERSION &method METHOD [& PARAMS ][& sid SID ]in which PARAMS represents the parameters for the requested method which is optional.Here's an example. If you want to make a request to the SYNO.API.Info API version 1 with the querymethod on your DiskStation whose address is http://myds.com:port (default port for http is 5000 and5001 for https) for the list of all available API methods, the corresponding parameters are:API name: SYNO.API.Infoversion: 1path: query.cgimethod: queryparams: query alland the request will look like this:http://myds.com:port/webapi/query.cgi?api SYNO.API.Info&version 1&method query&query allNote that an API's path and supported version information can be acquired by sending a request toSYNO.API.Info. The only API with a fixed location is SYNO.API.Info itself so that you can alwaysrequest SYNO.API.Info with /webapi/query.cgi.6Chapter 2: Get Started
Parsing ResponseAll API responses are encoded in the JSON format, and the JSON response contains elements rue” when the request finishes successfully, “false” when therequest fails with an error code.data object The data object contains all the response informationdescribed in each method.errorError codeAn integer number error code will be returned when a requestfails. There are two kinds of error codes: common error codesare error codes that are shared between all APIs; API errorcodes are API specific error codes that are listed under thecorresponding API spec.Following are examples for a failed request and successful request:Example: Response to a request with invalid parameters{"success":false,"error":101}Example: Response to a request for the package info of Download Station{"success":true,"data": {"is manager":true,"version":2269,"version string":"3.2-2269"}}Note that to demonstrate examples with clarity, only the data object is included in the responseexamples given in the following sections.7Chapter 2: Get Started
Common Error CodeThe codes listed below are general error codes for all Download Station APIs.CodeDescription100Unknown error101Invalid parameter102The requested API does not exist103The requested method does not exist104The requested version does not support the functionality105The logged in session does not have permission106Session timeout107Session interrupted by duplicate loginWorking ExampleThe following demonstrates a working example for requesting a download task list from DiskStation.To implement the example, simply replace the DiskStation address used in the example with yourDiskStation address and paste the URL to a browser. Then the JSON response will show up in aresponse page. Furthermore, you can find an online JSON parser to make the response morereadable for your experiments.Step 1: Get API InformationIn order to make API requests, you should first request SYNO.API.Info to get the SYNO.API.Auth APIinfo for session login and SYNO.DownloadStation.Task API info for download task api SYNO.API.Info&version 1&method query&query ata":{"SYNO.API.Auth": {"path": "auth.cgi","minVersion": 1,"maxVersion": 2},"SYNO.DownloadStation.Task": {"path": "DownloadStation/task.cgi","minVersion": 1,"maxVersion": 1}},"success": true}8Chapter 2: Get Started
Step 2: Session LoginAfter the SYNO.API.Auth path and supported version info are returned, you can log in a session byrequesting Auth API version 1 located at i/auth.cgi?api SYNO.API.Auth&version 2&method login&account admin&passwd 12345&session DownloadStation&format cookieResponse{"data":{sid: "ohOCjwhHhwghw"},"success": true}Step 3: Request Download APIAfter a session is logged in, you can continue to call the list method in SYNO.DownloadStation.Taskfor download task list. The cgi path and version are provided in the response of Step 1, and the list ofall tasks can be requested by excluding the offset and limit loadStation/task.cgi?api SYNO.DownloadStation.Task&version 1&method listResponse{"data":{"total":3,"offset":0,"tasks": [{"id":"dbid 001","type":"bt","username":"admin","title":"File 1","size":"123456","status":"downloading","status extra":null}, {"id":"dbid 002","type":"http","username":"bbb","title":"File 2","size":"654321","status":"waiting","status extra":null9Chapter 2: Get Started
}, {"id":"dbid 003","type":"ftp","username":"user1","title":"File 3","size":"654321","status":"finished","status extra":null}]},"success": true}From the response list, it can be observed that there are three tasks in Download Station. Let’s sayyou are interested in the task whose task ID is dbid 001 and want to know more details about it, soyou make another request to the getinfo method. In this request, you will need to add theparameter additional detail,transfer for the method to request detailed objects and transferthem in adStation/task.cgi?api SYNO.DownloadStation.Task&version 1&method getinfo&id dbid 001&additional detail,transferResponse{"data":{"tasks": [{"id":"dbid 001","type":"bt","username":"admin","title":"File 1","size":"123456","status":"downloading","status extra":null,"additional": {"detail": {"connected leechers":0,"connected seeders":0,"create ity":"auto","total sfer": {10Chapter 2: Get Started
"size downloaded":"54642","size uploaded":"435","speed download":"2605","speed upload":"0"}}}]},"success": true}Step 4: Session LogoutWhen you are finished with the procedures or if you want to switch to another user, you should log outthe current session. The session will be ended by calling the logout method in auth.cgi?api SYNO.API.Auth&version 1&method logout&session DownloadStation11Chapter 2: Get Started
ChapterChapter 3:3Base APIAPI ListThe following table is the overview of two fundamental APIs defined in this chapter:API NameDescriptionSYNO.API.InfoProvides available API info.SYNO.API.AuthPerforms session login and logout.SYNO.API.InfoOverviewAvailability: Since DSM 4.0Version: 1MethodQueryRequestParameterqueryDescriptionAPI names concatenated by "," or use "ALL" to getall supported APIs.Availability1 and laterExample:GET /webapi/query.cgi?api SYNO.API.Info&version 1&method query&query ALLResponseContains API description objects.Example:{"SYNO.API.Info": {"path": "query.cgi","minVersion": 1,"maxVersion": 1},"SYNO.API.Auth": {"path": "auth.cgi","minVersion": 1,"maxVersion": 2},12Copyright Synology Inc. All Rights Reserved.
"SYNO.DownloadStation.Schedule": {"path": "DownloadStation/schedule.cgi","minVersion": 1,"maxVersion": 1},"SYNO.DownloadStation.Task": {"path": "DownloadStation/task.cgi","minVersion": 1,"maxVersion": 1},"SYNO.DownloadStation.RSS.Site": {"path": "DownloadStation/RSSsite.cgi","minVersion": 1,"maxVersion": 1},"SYNO.DownloadStation.RSS.Feed": {"path": "DownloadStation/RSSfeed.cgi","minVersion": 1,"maxVersion": 1},"SYNO.DownloadStation.Statistic": {"path": "DownloadStation/statistic.cgi","minVersion": 1,"maxVersion": 1}}Response ObjectsHere are API description objects:ParameterDescriptionkeyAPI name1 and laterpathAPI cgi path1 and laterminVersionMinimum API version supported1 and latermaxVersionMaximum API version supported1 and laterAPI Error CodeNo specific API error codes.13AvailabilityChapter 3: Base API
SYNO.API.AuthOverviewAvailability: Since DSM 4.0Version: 2 (Since DSM vailabilityLogin account name1 and laterpasswdLogin account password1 and latersessionLogin session name1 and laterformatReturned format of session ID. Following are the twopossible options and the default value is cookie.2 and latercookie: The login session ID will be set to cookie.sid: The login sid will only be returned as responsejson data and the cookie will not be set.This option is not required to log into Download Station 2 and latersessions currently. However, please note that DSM 4.2and later includes a 2-step verification option. Ifenabled, the user requires a verification code to log intoDSM sessions.otp codeExample:GET /webapi/auth.cgi?api SYNO.API.Auth&version 2&method login&account admin&passwd 12345&session DownloadStation&format sidResponseParameterDescriptionAuthorized session ID. When the user log in withformat sid, cookie will not be set and each APIrequest should provide a request parameter sid sid along with other parameters.sidExample:{sid: "ohOCjwhHhwghw"}14Chapter 3: Base APIAvailability2 and later
LogoutRequestParameterDescriptionSession name to be logged outsessionAvailability1 and laterExample:GET /webapi/auth.cgi?api SYNO.API.Auth&version 1&method logout&session DownloadStationResponseNo specific response. It returns an empty success response if completed without error.API Error CodeCode15Description400No such account or incorrect password401Account disabled402Permission denied4032-step verification code required404Failed to authenticate 2-step verification codeChapter 3: Base API
ChapterChapter 4:4Download Station APIAPI ListThe following table is the overview of all Download Station APIs defined in this chapter. All DownloadStation APIs are required to log in with SYNO.API.Auth with session DownloadStation.API Name16DescriptionSYNO.DownloadStation.InfoProvides Download Station info and settings.Sets Download Station settings.SYNO.DownloadStation.ScheduleProvides advanced schedule settings.Sets advanced schedule settings.SYNO.DownloadStation.TaskProvides task listing and detailed task information.Performs task actions: create, delete, resume, pause.SYNO.DownloadStation.StatisticProvides total download/upload statistics.SYNO.DownloadStation.RSS.SiteProvides RSS site listing.Refreshes RSS site.SYNO.DownloadStation.RSS.FeedProvides RSS feed listing.Copyright Synology Inc. All Rights Reserved.
SYNO.DownloadStation.InfoOverviewAvailability: Since Download Station 3.2-2258Version: 1MethodGetInfoRequestNo parameters required.Example:GET /webapi/DownloadStation/info.cgi?api SYNO.DownloadStation.Info&version 1&method uild number of Download Station1 and laterversion stringstringFull version string of Download Station1 and lateris managerboolIf the logged in user is manager1 and laterExample:{"is manager":true,"version":2269,"version string":"3.2-2269"}GetConfigRequestNo parameters required.Example:GET /webapi/DownloadStation/info.cgi?api SYNO.DownloadStation.Info&version 1&method getconfig17AvailabilityChapter 4: Download Station API
ResponseParameterDescriptionPrivilegebt max downloadMax BT download speed in KB/s (“0”means unlimited)1 andlateradminonlybt max uploadMax BT upload speed in KB/s (“0”means unlimited)1 andlateradminonlyemule max downloadMax eMule download speed in KB/s(“0” means unlimited)1 andlateradminonlyemule max uploadMax eMule upload speed in KB/s (“0”means unlimited)1 andlateradminonlynzb max downloadMax NZB download speed in KB/s(“0” means unlimited)1 andlateradminonlyhttp max downloadMax HTTP download speed in KB/s(“0” means unlimited). For more info,please see Limitations1 and lateradmin onlyftp max downloadMax FTP download speed in KB/s (“0”means unlimited). For more info, pleasesee Limitations.1 and lateradmin onlyemule enabledIf eMule service is enabled1 and lateradmin onlyunzip service enabled If Auto unzip service is enabled for usersexcept admin or administrators group1 and lateradmin onlydefault destination2 and lateradmin only2 and lateradmin onlyDefault destinationemule default destina Emule default destinationtionExample:{"bt max download":13,"bt max upload":11,"emule enabled":true,"emule max download":13,"emule max upload":10,"ftp max download":0,"http max download":0,"nzb max download":10,"unzip service enabled":true,"default destination": "sharedfolder","emule default destination":"sharedfolder"}18AvailabilityChapter 4: Download Station API
lityPrivilegebt max downloadMax BT download speed in KB/s (“0”means unlimited)1 and lateradmin onlybt max uploadMax BT upload speed in KB/s (“0” meansunlimited)1 and lateradmin onlyemule max downloadMax eMule download speed in KB/s (“0”means unlimited)1 and lateradmin onlyemule max uploadMax eMule upload speed in KB/s (“0”means unlimited)1 and lateradmin onlynzb max downloadMax NZB download speed in KB/s (“0”means unlimited)1 and lateradmin onlyhttp max downloadMax HTTP download speed in KB/s (“0”means unlimited). For more info, pleasesee Limitations.1 and lateradmin onlyftp max downloadMax FTP download speed in KB/s (“0”means unlimited). For more info, pleasesee Limitations.1 and lateradmin onlyemule enabledIf eMule service is enabled1 and lateradmin onlyunzip service enable If Auto unzip service is enabled for usersdexcept admin or administrators group1 and lateradmin onlydefault destination2 and lateradmin only2 and lateradmin onlyDefault destinationemule default destin Emule default destinationationExample:GET /webapi/DownloadStation/info.cgi?api SYNO.DownloadStation.Info&version 1&method setserverconfig&bt max download 10&emule enabled trueResponseNo specific response. It returns an empty success response if completed without error.API Error CodeNo specific API error codes.Limitations1. Currently http max download and ftp max download share the same config value. Whenboth parameters are requested to be set at the same time, the requested ftp max download ratewill overwrite the requested http max download rate.2. Considering identical rates may be simultaneously used by the other packages other thanDownload Station, the HTTP and FTP max download rates will not affect tasks whose current statusis “downloading”. New rates will only be applied to those newly added/resumed HTTP/FTP tasks.19Chapter 4: Download Station API
SYNO.DownloadStation.ScheduleOverviewAvalibility: Since Download Station 3.2-2258Version: 1MethodGetConfigRequestNo parameters required.Example:GET /webapi/DownloadStation/schedule.cgi?api SYNO.DownloadStation.Schedule&version 1&method rivilegeenabledIf download schedule is enabled1 and lateradmin onlyemule enabledIf eMule download schedule is enabled1 and lateradmin onlyExample:{"enabled":true,"emule le enabledDescriptionAvailabilityPrivilegeIf download schedule is enabled1 and lateradmin onlyIf eMule download schedule is enabled1 and lateradmin onlyExample:GET /webapi/DownloadStation/schedule.cgi?api SYNO.DownloadStation.Schedule&version 1&method setconfig&enabled trueResponseNo specific response. It returns an empty success response if completed without error.API Error CodeNo specific API error codes.20Chapter 4: Download Station API
SYNO.DownloadStation.TaskOverviewAvailability: Since Download Station 3.2-2258Version: bilityOptional. Beginning task on the requested record. Default to “0”.1 and laterlimitOptional. Number of records requested: “-1” means to list all tasks.Default to “-1”.1 and lateradditionalOptional. Additional requested info, separated by ",". When anadditional option is requested, objects will be provided in thespecified additional option.1 and laterPossible options include: detail: returns Task Detail object transfer: returns Task Transfer object file: returns Task File object (BT only) tracker: returns Task Tracker object (BT only) peer: returns Task Peer object (BT only)Example:GET /webapi/DownloadStation/task.cgi?api SYNO.DownloadStation.Task&version 1&method list&additional tTotal number of records1 and lateroffsetintRequests offset1 and laterArrayArray of task objects1 and latertasksExample:{"total":12,"offset":10,"tasks": [{"id":"dbid 001","type":"bt","username":"admin","title":"TOP 100 MIX","size":"9427312332",21AvailabilityChapter 4: Download Station API
"status":"downloading","status extra":null,"additional": {"detail": {"connected leechers":0,"connected seeders":0,"create ity":"auto","total ": e":"41835","size downloaded":"0"}, ":"31689","size downloaded":"0"}]}}, {"id":"dbid rt us extra":null,"additional": {"detail": {"connected leechers":0,"connected seeders":0,"create ity":"auto","total pter 4: Download Station API
dTask IDs, separated by ",".1 and lateradditionalOptional. Additional requested info, separated by ",". When anadditional option is requested, objects will be provided in thespecified additional option.1 and laterPossible options include: detail: returns Task Detail object transfer: returns Task Transfer object file: returns Task File object (BT only) tracker: returns Task Tracker object (BT only) peer: returns Task Peer object (BT only)Example:GET /webapi/DownloadStation/task.cgi?api SYNO.DownloadStation.Task&version 1&method getinfo&id dbid 001,dbid 002&additional ray of Task objects.Example:{"tasks": [{"id":"dbid 001","type":"bt","username":"admin","title":"TOP 100 us extra":null,"additional": {"detail": {"connected leechers":0,"connected seeders":0,"create ity":"auto","total peers":0,23Chapter 4: Download Station APIAvailability1 and later
"uri":"http://mp3.com/mix.torrent"}}}, {"id":"dbid rt us extra":null,"additional": {"detail": {"connected leechers":0,"connected seeders":0,"create ity":"auto","total onal. Accepts HTTP/FTP/magnet/ED2K links or the filepath starting with a shared folder, separated by ",".3 and laterfileOptional. File uploading from client. For more info, pleasesee Limitations on page 30.1 and laterusernameOptional. Login username1 and laterOptional. Login password1 and laterOptional. Password for unzipping download tasks1 and laterOptional. Download destination path starting with a sharedfolder2 and laterpasswordunzip passworddestinationExample:POST /webapi/DownloadStation/task.cgiapi SYNO.DownloadStation.Task&version 1&method create&uri ftps://192.0.0.1:21/test/test.zip&username admin&password 12324Chapter 4: Download Station API
ResponseNo specific response. It returns an empty success response if completed without error.DeleteRequestParameteridforce completeDescriptionAvailabilityTask IDs to be deleted, separated by ",".1 and laterDelete tasks and force to move uncompleted download filesto the destination.1 and laterExample:GET /webapi/DownloadStation/task.cgi?api SYNO.DownloadStation.Task&version 1&method delete&id dbid 001,dbid 002&force complete trueResponseResponse is an array of response objects with following parameters.ParameterDescriptionAvailabilityidTask IDs1 and latererrorAction result. Error 0 for success.1 and laterExample:[{"error":405,"id":"dbid 001"},{"error":0,"id":"dbid 002"}]PauseRequestParameteridDescriptionTask IDs to be paused, separated by ",".Availability1 and laterExample:GET /webapi/DownloadStation/task.cgi?api SYNO.DownloadStation.Task&version 1&method pause&id dbid 001,dbid 002ResponseResponse is an array of response objects with following parameters.Parameterid25DescriptionTask IDsChapter 4: Download Station APIAvailability1 and later
errorAction result. Error 0 for success.1 and laterExample:[{"error":405,"id":"dbid 001"},{"error":0,"id":"dbid 002"}]ResumeRequestParameteridDescriptionTask IDs to be resumed, separated by ",".Availability1 and laterExample:GET /webapi/DownloadStation/task.cgi?api SYNO.DownloadStation.Task&version 1&method resume&id dbid 001,dbid 002ResponseResponse is an array of response objects with following Task IDs1 and laterAction result. Error 0 for success.1 and laterExample:[{"error":405,"id":"dbid 001"},{"error":0,"id":"dbid 002"}]EditRequestParameterDescriptionidTask IDs to be set destination, separ
request to SYNO.API.Auth API with the logout method. Making Requests . There are five basic elements for constructing a valid request to any of the APIs. API name: Name of the API requested version: Version of the API requested path: cgi path of the API. The path information can be retrieved by requesting SYNO.API.Info method: Method requested
