Use API to connect to Synology NAS services

---

---

Recently, in order to overcome with the large amount of data storage, the company's system has chosen to store data on NAS, so let's study how to connect this service via API.

Basically, you can refer to the official documentation for how to use it. Synology_File_Station_API_Guide, This article mainly records several APIs used and problems encountered.

To use each API of this service, you basically need to log in to obtain permissions. Each parameter is entrained in the form of a query string.

API Request:

Get
http://myds.com:port/webapi/auth.cgi?api=SYNO.API.Auth&version=3&method=login&account=admin&passwd=12345&session=FileStation&format=cookie

URL：http://{nasurl}:5000/webapi/auth.cgi
The port for http is 5000 and for https is 5001.

Query string:

api=SYNO.API.Auth

version=3

method=login

account=your account

passwd=your passwd

session=FileStation

format=cookie

Response:

{
    "data": {
        "did": "WeoBfHknZ4EllXoN4Jjds8ukcgyWyVJfQvoz60xTTpzMSpEaD8GU_yvrvjxK10h1Z4eMUhaxtyH5OphCCGl5Hw",
        "sid": "2ZLVB8UbL6EHnkI4uCO730lqNgJyzjBfhDcodeqNETcG_pMHr5yjt-gTYI0OtpzbmXAxlmZMXi3PyHkEyZHI0E"
    },
    "success": true
}

did is the ID of the nas service, and sid is the permission certificate obtained after logging in. When calling any API later, you can choose to carry it in the form of a cookie or query string.

This article uses the query string to carry sid, and the parameter is _sid=sid.

API Request:

Get
http://myds.com:5000/webapi/auth.cgi?api=SYNO.API.Auth&version=1&method=logout&session=FileStation

Query string:

api=SYNO.API.Auth

version=1

method=logout

session=FileStation

_sid=sid

Response:

{
    "success": true
}

After testing the sid's permissions, the validity period is quite long, so there is no need to log in and out frequently. My current approach involves checking the viability of the sid before each NAS operation. If the sid is invalid, I trigger a login action to acquire a new sid.

API Request:

Get
http://myds.com:5000/webapi/entry.cgi?api=SYNO.FileStation.CreateFolder&version=2&method=create&folder_path=%5B%22%2Fvideo%22%5D&name=%5B%22test%22%5D

Query string:

api=SYNO.FileStation.CreateFolder

version=2

method=create

folder_path=/path

name=folderName

_sid=sid

Response:

{
    "data": {
        "folders": [
            {
                "isdir": true,
                "name": "XDS",
                "path": "/SPM/XDS"
            }
        ]
    },
    "success": true
}

API Request:

Get
http://myds.com:5000/webapi/entry.cgi?api=SYNO.FileStation.Delete&version=2&method=start&path=%22%2Fvideo%2Fdel_folder%22

Query string:

api=SYNO.FileStation.Delete

version=2

method=start

path=/filePath

name=folderName

_sid=sid

Response:

{
    "data": {
        "taskid": "FileStation_657A5A3DF1C925ED"
    },
    "success": true
}

Executing deletion will return a taskid, which represents an action to perform deletion. To check whether the deletion is successful, you need to call another API.

API Request:

Get
http://myds.com:5000/webapi/entry.cgi?api=SYNO.FileStation.Delete&version=2&method=status&taskid=%22FileStation_51CEC9C979340E5A%22

Query string:

api=SYNO.FileStation.Delete

version=2

method=status

taskid=FileStation_657A5A483B021703

_sid=sid

Response:

{
    "data": {
        "finished": true,
        "path": "",
        "processed_num": 0,
        "processing_path": "",
        "progress": 1,
        "total": -1
    },
    "success": true
}

You can confirm whether the file or folder was deleted successfully.

API Request:

Post
http://myds.com:5000/webapi/entry.cgi?api=SYNO.FileStation.Upload&version=2&method=upload&path=/SPM/XD&create_parents=true&_sid=AgQzS8bUN7bJcfwfwHj4n2ZT_pjmC5PQAiKV_Xt27AgTO8B9uySZqhK9uQg8UosfMvBLUKrtYqrZtQKp1fJVqU

Query string:

api=SYNO.FileStation.Upload

version=2

method=upload

path=/folderPath

create_parents=true

_sid=sid

The Body part needs to use the form-data format:

Response:

{
  "data": {
    "blSkip": false,
    "file": "unnamed.png",
    "pid": 30385,
    "progress": 1
  },
  "success": true
}

Official document for file upload are not clear, and I am not sure whether the parameters must be placed in the query string or form-data. As a result, the file upload was successful when the file was placed on both sides...

API Request:

Get
http://myds.com:5000/webapi/entry.cgi?api=SYNO.FileStation.Download&version=2&method=download&path=%5B%22%2Ftest%2FITEMA_20445972-0.mp3%22%5D&mode=%22open%22

Query string:

api=SYNO.FileStation.Download

version=2

method=download

path=/filePath

mode=open or download

To open a file or folder using open, the Content-Type of the HTTP header can be set to the MIME type corresponding to the file.
Use download to download a file or folder, set the Content-Type of the HTTP header to application/octet-stream, and set the Content-Disposition to attachment, which tells the browser to treat it as an attachment and prompt for download.

_sid=sid

What needs to be noted is that for the file upload part, while the parameters are carried using query strings, they also need to be passed using form-data to be successful. I have tried this for a long time...

This is the first time I have connected to a NAS service. I usually provide APIs for people to connect to. After this experience, I realized that the API documentation must be well written, otherwise it will be really troublesome to rely on psychics when encountering problems.

Web

---

---