Synology API SDK

A C# SDK to access the Synology NAS APIs in DiskStation Manager (DSM).

Recommendations

I would recommend getting familiarized with the Synology APIs first before implementing this SDK, you will have a much easier time implementing it.

I have included Bruno API Client scripts (Bruno Synology API Scripts) to make it easier.

The official Synology API documentation can be found at Dev Center.

Implemented APIs

Included implementations in this SDK are some of the FileStation APIs and some of the Photos APIs.

There is no official Photos API documentation, what I have implemented in this SDK is what I gathered from various sources, including Synology's Community Forums, other repos, etc.

API	Description
SYNO.API.Info	Represents a request to information about the Synology APIs available for use on the target DiskStation.
SYNO.API.Auth	Represents a request to authenticate to Synology NAS.
SYNO.FileStation.Download	Represents a request to retrieve a list of files and folders in a directory.
SYNO.FileStation.List	Represents a request to retrieve a list of files and folders in a directory.
SYNO.FileStation.Search	Represents a request to retrieve a list of files and folders in a directory based on a search criteria.
SYNO.Foto.Browse.Album	Represents a request to retrieve a list of albums in your Personal Space.
SYNO.FotoTeam.Browse.Folder	Represents a request to retrieve a list of folders in the Shared Space.
SYNO.FotoTeam.Browse.Item	Represents a request to retrieve a list of items within a folder in the Shared Space.
FotoTeam.Browse.RecentlyAdded	Represents a request to retrieve a list of recently added items in the Shared Space.
SYNO.FotoTeam.Browse.Timeline	Represents a request to retrieve a list of item counts in the timeline by year and month in the Shared Space.
SYNO.FotoTeam.Download	Represents a request to download an item(s) in the Shared Space.
SYNO.FotoTeam.Search.Search	Represents a request to retrieve a count of items based on a keyword in the Shared Space.
SYNO.FotoTeam.Thumbnail	Represents a request to download an item's thumbnail in the Shared Space.

Installation

You will need to have the following in your appsettings.json file.

{
  "UriBase": {
    "ServerIpOrHostname": "<<SERVER_IP_OR_HOSTNAME>>",
    "Port": 5000,
    "UseHttps": false 
  }
}

This wires up DI for the base address in SdkConfigurationExtensions.ConfigureSynologyApiSdkDependencies class.

• ServerIpOrHostname: Required - This is usually your NAS IP address or if you have it configured to be accessible via a hostname. If this is not provided, the SDK will throw Microsoft.Extensions.Options.OptionsValidationException exception.
• Port: Optional - The NAS' default port number is 5000.
• UseHttps: Optional - Defaults to false.

The end result will be a base URI similar to http://127.0.0.1:5000.

Basic Usage

The SDK exposes two interfaces to interact with the Synology APIs, ISynologyApiRequestBuilder and ISynologyApiService.

ISynologyApiRequestBuilder

This interface constructs a URL by taking a Synology API Request and returning a string representing a complete URL to call a Synology API.

There is only one method in this interface, BuildUrl

ISynologyApiService

This interface is used to send an asynchronous GET request to the specified URL, generated by ISynologyApiRequestBuilder and returning a Synology API Response.

Example Code

/*
Configure Synology API SDK DI container.
*/
serviceCollection.ConfigureSynologyApiSdkDependencies(Configuration);

/*
Inject required services used to build the fully formed URL and the service to call the Synology API.
*/
var synoApiRequestBuilder = services.GetRequiredService<ISynologyApiRequestBuilder>();
var synoApiService = services.GetRequiredService<ISynologyApiService>();

/*
This will create a request to call SYNO.API.Info API endpoint. The parameters for each Synology API Requests will become query parameters when the final URL is formed.
*/
var apiInfoRequest = new ApiInfoRequest(
    method: Api.Info_Query,
    version: 1);

/*
`BuildUrl` takes in a Synology API request and returns a fully formed URL to call the specified Synology API.
In this example, the result will be: http://127.0.0.1:5000/webapi/entry.cgi?api=SYNO.API.Info&version=1&method=query
*/
var apiInfoUrl = synoApiRequestBuilder.BuildUrl(apiInfoRequest);

/*
`GetAsync` method will return a typed response from calling a Synology API
*/
var apiInfoResponse = await synoApiService.GetAsync<ApiInfoResponse>(apiInfoUrl, cancellationToken);

I have also included a Sample Consumer project for more complete usage examples.

Synology API Requests

• ApiInfoRequest
• LoginRequest
• LogoutRequest
• FileStationDownloadRequest
• FileStationListRequest
• FileStationSearchRequest
• FotoBrowseAlbumRequest
• FotoTeamBrowseFolderRequest
• FotoTeamBrowseItemRequest
• FotoTeamBrowseRecentlyAddedRequest
• FotoTeamBrowseTimelineRequest
• FotoTeamDownloadRequest
• FotoTeamSearchSearchRequest
• FotoTeamThumbnailRequest

It is possible I have not included all of the parameters in the official API docs for each request. If that is the case, there is an option to add additional parameters to each request via a key-value dictionary when creating the request object.

Contributing

Follow the naming conventions for Synology API Request and Response classes.

Example:

• API endpoint: SYNO.FileStation.List
• Request-Response C# classes: FileStationListRequest.cs and FileStationListResponse.cs

Add corresponding unit tests following the existing tests patterns.

Make sure to test by calling your NAS and getting a successful response.

Giving Back

If you find this SDK useful in any way, consider getting me a coffee by clicking on the image below. I would really appreciate it!