REST API Feedback

Firstly thank you for making and maintaining Syncthing, it’s fantastic!

Secondly this is not a criticism, just a constructive feedback. Please don’t take it the wrong way.

  1. Logic in the UI rather than in backend. In particular when it comes to status like “Out of Sync” or “Locally changed”, these are “computed” in the UI based on logic that is present in the UI only. IMHO these should be “computed” in the backed returned by the API, not decided by the UI. If someone wanted to write their own UI then you’d have to look at a logic in the Web UI to make it work similar way. Everything should be returned by the API so different API clients work the same way.

  2. RESTful API URL scheme, in particular resource names. I don’t think that URL and resource naming scheme for REST is defined by any standard, however from my past work and use of API linters, the URL should be in form of POST /v1/db/foldername/scan, rather than POST /rest/db/scan?folder=foldername. Using query strings for resource names is not very RESTy… Also instead of making something as obsolete in the documentation, please consider versioning scheme. I know this is debatable, maybe for future consideration.

4 Likes

The API has grown “organically” over time, without clear guidelines as to what the structure should look like eventually. The developers are well aware of the fact that some of it is convoluted / inconsistent / messy. But so far we’ve highly valued preserving compatibility, noting things for an eventual break with a tentative version 2. Right now there is no definite plan as to when something like that might happen. It will definitely need very good coordination with API consumers, of which there are quite a few by now - some of which we’ve probably never even heard of. That cries for an extended migration period providing both APIs in parallel I suppose.

I agree on the point that non-trivial calculations should be done in the backend already. Just that the threshold for “trivial” is highly subjective. For example, is the completion percentage based on bytes remaining or files remaining? This particular one is provided by the backend, but some frontend could want to do it differently, so the raw values are conveyed in addition.

2 Likes

Yes, since I’ve wrote a UI for Syncthing I can only second that. However, some things are also better computed on UI-level (e.g. the overall status as there are different preferences on what to consider for it).

That’s a very important point. For v1 Syncthing should avoid breaking changes. Having to adapt all projects using the API would be very annoying.

Different people have different preferences. I personally like the approach taken by Syncthing. I always find it weird when some parameters are part of the path and some passed as query parameters. Having all parameters at one place seems consistent. Additionally, what if I wanted to request the scan for multiple folders at once? A simple use-case that wouldn’t really fit into the POST /v1/db/foldername/scan form. I would only prefer the path-from if there’s really a strictly hierarchical underlying data structure.

1 Like