Transcription
Developer's Guide forDSM Login Web API1
Table ofContentsTHIS DOCUMENT CONTAINS PROPRIETARY TECHNICALINFORMATION WHICH IS THE PROPERTY OF SYNOLOGYINCORPORATED AND SHALL NOT BE REPRODUCED, COPIED,OR USED AS THE BASIS FOR DESIGN, MANUFACTURING, ORSALE OF APPARATUS WITHOUT WRITTEN PERMISSION OFSYNOLOGY INCORPORATED.Chapter 1: Introduction01Chapter 2: Getting Started02Chapter 3: Base API12Copyright and Disclaimer Notices17
Chapter 1: IntroductionChapter 1: IntroductionThe DSM Login Web API developer’s guide explains how to perform DSM logins using Web APIand expands your applications based on the APIs of Synology NAS, allowing your applicationsto interact with DSM or DSM Packages via HTTP/HTTPS requests and responses.This document explains the basic guidelines on how to use APIs, which we suggest reading allthe way through before you jump into the other API specifications.01
Chapter 2: Getting StartedChapter 2: Getting StartedThis chapter explains how to execute and complete API processes in the following fivesections: API Workflow: Briefly introduces how API works. Making API Requests: Describes how to construct API requests. Parsing API Response: Describes how to parse API responses. Common Error Code: Lists of all common error codes that might be returned from all APIs. Working Examples: Provides File Station operations as examples.All query examples are based on DSM 7.0 version.API WorkflowThe following five-step and easy-to-follow workflow show how to make your applicationsinteract with APIs.Step 1: Retrieve API Information02
Chapter 2: Getting StartedFirst, your application needs to retrieve API information from the target Synology NAS toknow which APIs are available for use on the target Synology NAS. This information can beaccessed simply through a request to /webapi/entry.cgi with SYNO.API.Info API parameters.The information provided in the response contains available API name, API method, API pathand API version. Once you have all the information at hand, your application can make furtherrequests to all available APIs.Step 2: LoginTo make your application interact with Synology production, your application needs to log inwith an account and password first. The login process is making a request to SYNO.API.AuthAPI with the login method. If successful, the API returns an authorized session ID. You shouldkeep it and pass it in making other API requests.Step 3: Making API RequestsOnce successfully logged in, your application can start to make requests to all availableSynology production APIs. In "Making API Requests", instructions on how to form a valid APIrequest and how to decode response information will be given.Step 4: LogoutAfter finishing with the steps above, your application can end the login session by makinganother request to SYNO.API.Auth API with the logout method.Making API RequestsThere are five basic elements that are used to construct a valid request to any API: path: Path of the API. The path information can be retrieved by requesting SYNO.API.Info. api: Name of the API requested. version: Version of the API requested. method: Method of the API requested. sid: (Optional) If you already store Cookies on the login request with SYNO.API.Auth API andwill pass this cookie on HTTP/HTTPS header, you may ignore this parameter. Otherwise, passeither HTTP/HTTPS GET/POST method with " sid" argument which value can be retrievedfrom the login response of SYNO.API.Auth API.The syntax for the request is as follows:GET /webapi/ PATH ?api API &version VERSION &method METHOD [& PARAMS ][& sid SID ] PARAMS represents the parameters for the requested method which is optional. You shouldlook up requestFormat information that can be retrieved by SYNO.API.Info. If requestFormatindicates "JSON", the params value should be JSON encoded.03
Chapter 2: Getting StartedTo make a request to the SYNO.API.Info API version 1 with the query method on yourSynology NAS which address is https://myds.com:port (default port for HTTP is 5000 or 5001for HTTPS) for the list of all available API methods, the corresponding parameters are: path: entry.cgi api: SYNO.API.Info version: 1 method: queryThe request will look like this:https://myds.com:port/webapi/entry.cgi?api SYNO.API.Info&version 1&method queryNotes: An API's path and supported version information can be acquired by sending a request toSYNO.API.Info. The location of SYNO.API.Info is fixed so that you can always request SYNO.API.Info with /webapi/entry.cgi.Parsing API ResponseAll API responses are encoded in the JSON format except download behavior, and the JSONresponse contains elements as follows:KeyValueDescriptiontrue/false"true": the request completes successfully; "false":the request fails with an error data.data JSON-Style Object The data object contains all response informationdescribed in each method.error JSON-Style Object The data object contains error information when arequest fails. The basic elements are described inthe next table.successThe following describes the format of error information in error element:KeycodeValueError CodeDescriptionAn error code will be returned when a requestfails. There are two kinds of error codes: acommon error code which applies to all APIs, anda specific API error code (described under thecorresponding API spec).04
Chapter 2: Getting Startederrors JSON-Style Array The array contains detailed error information ofeach file. Each element in an error is a JSON-StyleObject which contains an error code and otherinformation, such as a file path or name.Notes: When there is no detailed information, this errorelement won’t be responded.Example 1Respond to an invalid request without a method ry.cgi?api SYNO.FileStation.Info&version 1Failed mple 2Respond to an invalid request due to an error code and to show more information about ntry.cgi?api SYNO.FileStation.CreateFolder&method create&version 1&folder path %2Ftest&name %3A05
Chapter 2: Getting StartedFailed rors":[{"code":408,"path":"/test/:"}]}}Example 3Respond to a successful request and retrieve information from File .cgi?api SYNO.FileStation.Info&version &method get06
Chapter 2: Getting StartedSuccess Response:{"success":true,"data": {"enable list usergrp": false,"hostname": "myds","is manager": true,"items": [{"gid": 100},{"gid": 101}],"support file request": true,"support sharing": true,"support vfs": true,"support virtual": {"enable iso mount": true,"enable remote mount": true},"support virtual protocol": ["cifs","nfs","iso"],"system codepage": "cht","uid": 1026}}Notes: Only the data object is provided in the given response samples.07
Chapter 2: Getting StartedCommon Error CodesThe codes listed below are common error codes of wrong parameters or a failed login for allWeb APIs.CodeDescription100Unknown error.101No parameter of API, method or version.102The requested API does not exist.103The requested method does not exist.104The requested version does not support the functionality.105The logged in session does not have permission.106Session timeout.107Session interrupted by duplicated login.108Failed to upload the file.109The network connection is unstable or the system is busy.110The network connection is unstable or the system is busy.111The network connection is unstable or the system is busy.112Preserve for other purpose.113Preserve for other purpose.114Lost parameters for this API.115Not allowed to upload a file.116Not allowed to perform for a demo site.117The network connection is unstable or the system is busy.118The network connection is unstable or the system is busy.119Invalid session.120-149150Preserve for other purpose.Request source IP does not match the login IP.Working ExampleThe following demonstrates a working example for requesting a file operation from theSynology NAS. To implement this example, simply replace the Synology NAS address used inthe example (myds.com:port) with your Synology NAS address and paste the URL to a browser.Then the JSON response will show up in a response page.08
Chapter 2: Getting StartedStep 1: Retrieve API InformationIn order to make API requests, you should first request to /webapi/entry.cgi with SYNO.API.Infoto get the SYNO.API.Auth API information for logging api SYNO.API.Info&version 1&method query&query SYNO.API.Auth": {"path": "entry.cgi","minVersion": 1,"maxVersion": 7},"SYNO.FileStation.List": {"path": "entry.cgi","requestFormat":"JSON""minVersion": 1,"maxVersion": 2},"SYNO.VideoStation.Info": {"path": "VideoStation/info.cgi","minVersion": 1,"maxVersion": 1}, },"success": true}09
Chapter 2: Getting StartedStep 2: LoginAfter the SYNO.API.Auth path and supported version information are returned, you can log into a DSM session by requesting SYNO.API.Auth API version 6 located at bapi/entry.cgi?api SYNO.API.Auth&version 6&method login&account USERNAME &passwd PASSWORD Response:{"data":{"did": "Prl-lFg-ZP0LRrGlyP kXM1AQ-4doGBIM6NA","is portal port": false,"sid": "NTT0mWED6M-pYHb8l 0C3NULg 7PTxy0GZx8"},"success": true}Step 3: Request a DSM APIAfter you have signed in a session, you can continue to call the APIs of DSM listed in SYNO.API.Info. We show a sample of SYNO.FileStation.List API. The cgi path and version are provided inthe response of Step 1, and the list of all tasks can be requested by excluding the offset andlimit try.cgi?api SYNO.FileStation.List&version 1&method list share10
Chapter 2: Getting StartedResponse:{"data": {"offset": 0,"shares": [{"isdir": true,"name": "video","path": "/video"},{"isdir": true,"name": "photo","path": "/photo"}],"total": 2},"success": true}It can be observed on the response list that there are two shared folders in File Station. Ifyou're interested in learning more about the share list WebAPI query format, you can acquirethe document from File Station.Step 4: LogoutAfter you have finished the procedure, you should sign out of the current session. The sessionwill be ended by calling the logout method in SYNO.API.Auth. If you don't use a cookie, logout the session by passing the sid parameter. It is a good habit to sign out a session whenyou're i?api SYNO.API.Auth&version 6&method logout[& sid eEM-UReSr-KjiEDVC0C3NULg 7PTxy0GZx8]11
Chapter 3: Base APIChapter 3: Base APIAPI ListThe following table is the overview of two fundamental APIs defined in this chapter:API NameDescriptionSYNO.API.InfoProvide available API info.SYNO.API.AuthPerform log in and log out.SYNO.API.InfoOverviewAvailability: Since DSM 4.0Version: abilityAPI names, separated by a comma "," or use "all"to get all supported APIs.1 and laterExample:GET /webapi/entry.cgi?api SYNO.API.Info&version 1&method query12
Chapter 3: Base APIResponse:Contains API description objects.ParameterDescriptionAvailabilitykeyAPI name.1 and laterpathAPI path.1 and laterminVersionMinimum supported API version.1 and latermaxVersionMaximum supported API version.1 and laterIf this value shows "JSON," use the JSON encoderfor all other parameter values.1 and : {"path": "entry.cgi","minVersion": 1,"maxVersion": 7},"SYNO.FileStation.List": {"path": "entry.cgi","requestFormat":"JSON""minVersion": 1,"maxVersion": 2},"SYNO.VideoStation.Info": {"path": "VideoStation/info.cgi","minVersion": 1,"maxVersion": 1}, },"success": true}13
Chapter 3: Base APIAPI Error CodeNo specific API error codes.SYNO.API.AuthOverviewAvailability: Since DSM 6.0Version: 3 7; 6 sswdsessionDescriptionAvailabilityLogin account name.3 and laterLogin account password.3 and laterOptional - Login session name for DSMAppplications.3 and laterOptional - Returned format of session ID.Following are the two possible options and thedefault value is cookie.formatcookie: The login session ID will be set to "id" keyin cookie of HTTP/HTTPS header of response.3 and latersid: The login sid will only be returned asresponse JSON data and "id" key will not be set incookie.otp codeenable devicetokendevice namedevice idOptional - 2-factor authentication option withan OTP code. If it’s enabled, the user requires averification code to log into DSM sessions.3 and laterOptional - Omit 2-factor authentication (OTP) witha device id for the next login request.6 and laterOptional - To identify which device can be omittedfrom 2-factor authentication (OTP), pass this valuewill skip it.6 and laterOptional - If 2-factor authentication (OTP) hasomitted the same enabled device id, pass thisvalue to skip it.6 and later14
Chapter 3: Base APIExample 1: LoginGET /webapi/entry.cgi?api SYNO.API.Auth&version 6&method login&account USERNAME &passwd PASSWORD &session FileStation&format cookieExample 2: Login with OTPGET /webapi/entry.cgi?api SYNO.API.Auth&version 6&method login&account USERNAME &passwd PASSWORD &otp code OTP CODE Example 3: Login with OTP and to enable to omit 2-factor verificationGET /webapi/entry.cgi?api SYNO.API.Auth&version 6&method login&account USERNAME &passwd PASSWORD &otp code OTP CODE &enable devicetoken yes&device name DEVICE NAME Example 4: Login with omitted OTPGET /webapi/entry.cgi?api SYNO.API.Auth&version 6&method login&account USERNAME &passwd PASSWORD &device name DEVICE NAME &device id DID Response: data object horized session ID. When the user log in withformat sid, cookie will not be set and each APIrequest should provide a request parameter3 and latersid sid along with other parameters.didis portal portA.K.A device id, to identify which device.6 and laterIrrelevant.6 and laterExample:{"data":{"did": "Prl-lFg-ZP0LRrGlyP kXM1AQ-4doGBIM6NA","is portal port": false,"sid": "NTT0mWED6M-pYHb8l 0C3NULg 7PTxy0GZx8"},"success": true}15
Chapter 3: Base APILogoutRequest:No specific other parameters.Example:GET /webapi/entry.cgi?api SYNO.API.Auth&version 6&method logoutResponse:No specific response. It returns with an empty "success" response if completed without error.API Error CodesCodeDescription400No such account or incorrect password.401Disabled account.402Denied permission.4032-factor authentication code required.404Failed to authenticate 2-factor authentication code.406Enforce to authenticate with 2-factor authentication code.407Blocked IP source.408Expired password cannot change.409Expired password.410Password must be changed.16
Copyright and Disclaimer NoticesCopyright and Disclaimer NoticesSynology Inc. 2013-2021 Synology Inc.All rights reserved.No part of this publication may be reproduced, stored in a retrieval system, or transmitted,in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise,without prior written permission of Synology Inc., with the following exceptions: Any personis hereby authorized to store documentation on a single computer for personal use only andto print copies of documentation for personal use provided that the documentation containsSynology’s copyright notice.The Synology logo is a trademark of Synology Inc.No licenses, express or implied, are granted with respect to any of the technology described inthis document. Synology retains all intellectual property rights associated with the technologydescribed in this document. This document is intended to assist application developers todevelop applications only for Synology-labelled computers.Every effort has been made to ensure that the information in this document is accurate.Synology is not responsible for typographical errors.Synology Inc.9F, No. 1, Yuandong Rd.Banqiao Dist., New Taipei City 220632, TaiwanSynology and the Synology logo are trademarks of Synology Inc., registered in the UnitedStates and other countries.Marvell is registered trademarks of Marvell Semiconductor, Inc. or its subsidiaries in the UnitedStates and other countries.Freescale is registered trademarks of Freescale Semiconductor, Inc. or its subsidiaries in theUnited States and other countries.Other products and company names mentioned herein are trademarks of their respectiveholders.Even though Synology has reviewed this document, SYNOLOGY MAKES NO WARRANTY ORREPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITSQUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS ARESULT, THIS DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE17
Copyright and Disclaimer NoticesENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL SYNOLOGY BE LIABLE FORDIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROMANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of suchdamages.THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALLOTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Synology dealer, agent, or employee isauthorized to make any modification, extension, or addition to this warranty.Some states do not allow the exclusion or limitation of implied warranties or liability forincidental or consequential damages, so the above limitation or exclusion may not apply toyou. This warranty gives you specific legal rights, and you may also have other rights whichvary from state to state.18
Copyright and Disclaimer NoticesSYNOLOGYINC.9F, No. 1, Yuandong Rd.Banqiao Dist., New Taipei City 220632TaiwanTel: 886 2 2955 1814SYNOLOGYAMERICA CORP.3535 Factoria Blvd SE, Suite #200,Bellevue, WA 98006USATel: 1 425 818 1587SYNOLOGYUK LTD.Unit 5 Danbury Court, Linford Wood,Milton Keynes, MK14 6PLUnited KingdomTel.: 44 (0)1908048029SYNOLOGYFRANCE102 Terrasse Boieldieu (TOUR W)92800 PuteauxFranceTel: 33 147 176288SYNOLOGYGMBHGrafenberger Allee 29540237 DüsseldorfDeutschlandTel: 49 211 9666 9666SYNOLOGYSHANGHAI200070, Room 201,No. 511 Tianmu W. Rd.,Jingan Dist., Shanghai,Chinasynology.comSynology may make changes to specifications and product descriptions at any time, without notice. Copyright 2021 Synology Inc. All rights reserved. Synology and other names of Synology Products are proprietarymarks or registered trademarks of Synology Inc. Other products and company names mentioned herein aretrademarks of their respective holders.19SYNOLOGYJAPAN CO., LTD.4F, No. 3-1-2, Higashikanda,Chiyoda-ku, Tokyo, 101-0031Japan
The DSM Login Web API developer’s guide explains how to perform DSM logins using Web API and expands your applications based on the APIs of Synology NAS, allowing your applications to interact with D
