nextcloud
Attachment API questions, possible tweaks
Hey all, great to see the recent merge of the attachments API :+1: 🎉 @oli-ver @enjeck
I'm working to integrate it into a client and have a few questions with some possible user-centric suggestions. My knowledge about attachments in Nextcloud independent of this API is limited though, so I could be misunderstanding :)
Why is the random string used for API upload filenames, compared to web (OCA.Text) using the recognisable name?
Problems - A readable filename is a better experience for the user in non-WYSIWYG editors. Plus being able to know what the filename is probably going to be removes the need to, after every attachment upload completes, update the text in the note while it's being edited. The server also ends up with a bunch of more usefully named files.
Suggestion - Use the filename when it's unique. Upon name conflicts use the Nextcloud convention if there is one, or browser download conflict style suffixing (as users are familiar with this).
Why do the API uploads get stored alongside the note, compared to the web client's in a .attachments.<fileid> directory?
Problems - It lacks consistency with the web UI and arguably creates a bit of a mess. Plus if the discarding of filenames is resolved, having one namespace (per category) is more likely to result in filename conflicts.
Edit: also, attachments don't get deleted automatically with the note, unlike those in an .attachments.<fileid> directory.
A further edit: the attachments also don't get moved into the category sub-folders, resulting in disconnection from the note (again those with .attachments.<fileid> form do).
Suggestion - Do the same thing as the web editor.
How does one delete an attachment?
I'm guessing there's no garbage collection as that would mean parsing each markdown file to determine which files are no longer used? Access in the API would be useful.
If my suggestions make sense and nobody else is ready to jump on them I can have a look.
I'll hold on integrating changes into the client for now.
Comments are for MR #1600, original issue #826
Use the filename when it's unique. Upon name conflicts use the Nextcloud convention if there is one, or browser download conflict style suffixing (as users are familiar with this).
Yeah, I like this approach
Why do the API uploads get stored alongside the note, compared to the web client's in a
.attachments.<fileid>directory?
Reading previous discussions about this, I'm not quite sure why. It appears they tried to avoid using the fileID in the reference for two reasons:
- The file ID will change if you move your notes to another server. As a consequence, no attachment will work anymore.
- The file ID is not very intuitive for humans. People, who work with the plain Markdown code, can't see which attachment is behind this ID.
Note for anyone else reading this:
The attachment paths are relative to the note. E.g., if the notes path is /notes and the note's category is Animals, then the attachment path frog.jpg will be resolved to /notes/Animals/frog.jpg and the attachment path ../frog.jpg will be resolved to /notes/frog.jpg. For security reasons, we've restricted the path resolution to the notes path, for now. E.g., if the notes path is /notes and the note's category is Animals, then the attachment path ../../frog.jpg is invalid.
Since the path is relative to the notes path, it is fully transparent. But: Changing the note's category may lead to losing the connection to the attachment.
Hey @enjeck, thanks for getting back to me. Sorry this got a bit long and devil's advocate-y! :)
The file ID will change if you move your notes to another server. As a consequence, no attachment will work anymore.
Presuming this means Nextcloud has no mechanism for running logic as part of a restoration, providing something like a Remap Attachments After Migration function via the preferences would be one way to cater for this. It can determine each note's old file id from the directory names in the markdown and rename the attachments directory and update the contents.
Does anything exist already for the attachments created by the web and Android?
The file ID is not very intuitive for humans. People, who work with the plain Markdown code, can't see which attachment is behind this ID.
Agreed. Drifting a little further from the practical but I'd prefer avoiding having the attachment directory in the markdown and do the translation in the backend instead, storing attachments transparently in their own folders per note with simple filenames in the markdown. But that wasn't the decision made by those who built this system into the web UI and Android app in time past (and it would focus on a better user experience in this ecosystem over direct note exportability to use from a filesystem).
Back in the practical, why should the API have a different approach to what's already in use in production web app and Android app?
I wonder if it's easier to just keep the existing struture in the meantime and instead explore moving things around when the category is changed.
(from #1633, keeping discussion in one place)
For changing category would one also need to parse all other notes in the source directory to ensure no other note is using the attachment?
And then there's attachment deletions. Having the per-note attachment directories would at least be a slightly simpler GC task (especially if folk delete note files by hand). I think an API addition or server some server parsing fu is needed to provide for deletion, but in the case of that not being immediately built, storing attachments in note-specific directories makes less of a mess until it is.
I wonder how backwards compatible it is.
(also from #1633)
What backwards compatibility are you thinking of here? With the released version of the API? Are there any consumers?
Or do you mean the directory structure and markdown? In that case, again, isn't this the same as what the rest of the ecosystem already uses in production for attachments?
Presuming this means Nextcloud has no mechanism for running logic as part of a restoration, providing something like a Remap Attachments After Migration function via the preferences would be one way to cater for this. It can determine each note's old file id from the directory names in the markdown and rename the attachments directory and update the contents.
Just discussed with @juliusknorr about this and he says Text does use the fileId, but it ensures that attachment links are relative links so that they are not broken when servers are moved. I still need to look into how this is done there
What backwards compatibility are you thinking of here? With the released version of the API? Are there any consumers?
Yes, I meant with respect to the released version of the API. But we should be fine to release a new version even with breaking changes.
Just discussed with @juliusknorr about this and he says Text does use the fileId, but it ensures that attachment links are relative links so that they are not broken when servers are moved. I still need to look into how this is done there
Yeah exactly, because they're just relative links even if the fileIds are out of sync the content will still load.
ie. this will work
- Create a note on a server, add an attachment to it
- Copy the note file and its attachment folder to another server
- See that the note has retained the ability to display the attachment
But... extending on those steps this doesn't work 4. Move that note to a new category/folder
Unfortunately (but unsurprisingly) only an .attachments.<fileId> folder for the note's current fileId gets automatically moved with the note.
However a) it's still an improvement on the current API logic which doesn't move attachments in any circumstance and b) this is an issue that exists with the current attachment system in the web and Android editor; it's not a new issue related to the API.