API Clarifications

Hey all!

I've been developing my SiYuan plugin for a while now, but since documentation is very sparse, I've always been kind of freestyling some things, and that has been giving some problems. Since I saw that the community here is very friendly, I chose to ask for some help.

Question 1: Developer resources

I've not yet found a fully documented API reference for the Kernel or Plugins. So far I've been using:

• Plugin Quick Start guide
• API Reference

The second link is especially useful, since it explains a good part of the Plugin APIs and Kernel APIs, therefore it's my primary source. Unfortunately it's not available in English so I have to use an auto-translator extension.

I'm not sure it's an official source either, so some recently added endpoints appear to be missing, like those added in v3.1.27.

If you know of any other better source, please share it!

Question 2: Proper Asset Syncing

Another problem that has been puzzling me is the difference between files, assets, and how it impacts sync across devices.

There are different API endpoints for Resource files and Files, but I've never really understood the difference.
With either, when uploading a file/asset, it only gets synced to the other devices if it didn't previously exist, so for example:

• Plugin creates file ./data/assets/drawing.svg with content "ABC" on device 001
• Device 002 syncs the workspace, gets file ./data/assets/drawing.svg with content "ABC"
  • ABC and DEF are placeholders for any actual SVG content
• Device 002 edits the file from the plugin, sets content DEF
• Device 001 sync the workspace, the file content remains ABC
  • Most of the times, a notification for a file sync conflict appears

I've tested with both the Resource Files and Files API.

So far my solution has been to manually delete the old resource files, so for example:

• User creates asset with content ABC, it's uploaded as assets/fileID-syncID.svg

  • fileID is the name of the file
  • syncID is the string that SiYuan uses for this type of things, it's in format datestamp-randomString

• User edits the image, it's uploaded as assets/fileID-NEWSyncID.svg

  • Notice that the syncID has now changed to NEWSyncID

• A protyle search-and-replace is run to replace everywhere assets/fileID-syncID.svg to assets/fileID-NEWsyncID.svg

• assets/fileID-syncID.svg is deleted (if everything was succesful)

However, I'm sure that there's a better solution to this. Editing the protyle to change SyncIDs is a finnicky solution which I'm not very proud of, it could cause problems.

I've also noticed that SiYuan supports file changes from an external image editor, but since the docs strongly discourage the usage of native file operation APIs, I've never used it.

Question 3: Image caching

Is there a specific API to refresh the cached images in the SiYuan documents? I guess that a whole UI reload would work, but it's a bit violent.

My solution for the problem, before I implemented the "changing SyncID system" described before, was using fake GET parameters, so an example asset URL would be like assets/awiottm-20250415150234-aaf7peb.svg?antiCacheID=100, and after the user edited their document, it would become assets/awiottm-20250415150234-aaf7peb.svg?antiCacheID=101, which triggers an image repaint.

Again, I'm sure there is a better solution, as this still requires editing the protyle, which I dislike.

Thanks for your feedback! Please let me know if I need to provide clarifications, code examples, etc. I'm always willing to contribute!