API Draft

[brantje]

I've published a API draft here.
This is the API the app will use in the end.

Keep in mind that the app might change the name, in that case the endpoints will change.

[ThomasDaheim]

Thanks @brantje , a few comments from my end:

• "Create a note" is not consistent: shouldn't it return "title": "New content" in your example?

• "Update a note": shouldn't that return "title": "Note title" for your parameters

• "Delete" returns nothing? How would I know that the call failed for some reason?

• Would you need to use update to change note name / group? Could be a killer for large notes (e.g. with images). A "Rename" call might be a better option?

• I could think of a number of mass updates that one might want to do (move all notes from one group to another, ...)

• In case we would want to support .md as well we would need to add file type or similar as parameter?

• There are a few requests for hierarchical groups. How would that work with this API?

[brantje]

• Fixed
• Fixed
• Fixed
• Good idea. How about PUT /api/v2.0/note/{id}/rename with possible fields title and group.
• Maybe, defaults to html?
• I've been thinking about a tree structure too would be nice for notes. Can you look into this?

[ThomasDaheim]

PUT looks good for single action. Still would leave any mass operations open since you have {id} in the path.

Tree structure: Have thought about that for a while now. The challenge I can see is to where to store the group information if you use files. Three choices come to (my) mind:

1. Extend current scheme to e.g. [group1-group2-group3,group4,group5-group6] for hierarchies (via "-" and multiple groups (via ",")
   Pro: filename has all info, never needed to parse file e.g. to show notes tree
   Con: file names can get messy

2. hierarchical groups as directories
   Con: can't have one note in multiple groups; parsing & moving seems to be more complex

3. store group info in some tag where they don't interfere with the editor
   Pro: short filenames
   Con: Parsing required for e.g. find all notes for a given group

4. store group info in file meta information - no idea if this can be done independent of OS, ...

As for the api: could use a similar syntax for passing group information as a string as option 1)

The guys from the notes app had a discussion as well (nextcloud/notes#8) with groups vs. tags. Maybe there is something to learn from that?

[brantje]

Ahh yea, the never ending tag vs. tree structure discussion.
In my opinion, if tags are proper implemented, you can use them as a tree structure.

Personally i would go for tags, but what do others think?

[ThomasDaheim]

Tags seem to be more flexible. But UI around it is probably a bit more complex.

How does e.g. OneNote do it? They seem to have a structure in the UI:

• Notebook
  • Section
    • Page

So more like a tree and I can't seem to find a way to add tags. That seems to be sufficient for a large number of people out there...

But of course its largely a matter of taste, I would think. Some people prefer hierarchies, others tag clouds. I could live with tags as well, currently I wouldn't have the need for any hierarchy deeper than one level. And thats the same as tags :-)

[brantje]

Yea but we have limited space in the sidebar, and i hate horizontal scrolling.
We could allow 2 nesting levels:

• Folder 1
  • Subfolder

This way, we can keep the sidebar clean, and still support folders.

[ThomasDaheim]

I'm fine with that. Maybe it would possible to keep API and code in general without the restriction to to 2 levels? So we would be open for any further improvements...

But it would mean that you can't have a note with two different tags assigned. or we would have levels and tags as different concepts.

[brantje]

Yea, do you have an idea how to implement it?
We can add a folder property to the object.

[ThomasDaheim]

I don't like "folder" because it suggests a form of implementation/presentation :-) Group is OK for me since it also keeps the wording from ownNote.

As for implementation see my post above. Something along the lines of "Extend current scheme to e.g. [group1-group2-group3,group4,group5-group6] for hierarchies (via "-" and multiple groups (via ",")" that would keep the API down to one parameter - a serialized tree.

[enoch85]

I don't like "folder" because it suggests a form of implementation/presentation :-) Group is OK for me since it also keeps the wording from ownNote.

Agreed.

[brantje]

@ThomasDaheim for renaming / deleting groups, what endpoint url shall we make?

[korelstar]

In the last days, I thought about how to provide categories for the "Nextcloud Notes" app. I came to a similar conclusion: don't show all hierarchy levels in the sidebar, but only show the first level. But, nevertheless, I would not restrict the allowed levels to this (some people's will be comprehensively structured). Instead, show the deeper levels in the list of notes. I.e., the notes belonging to the current primary level are listed sorted by their (sub-)category/group and then by their title. Before a new category/group begins, a head with the respective name is shown. Example:

The sidebar shows:

• Project 1
• Project 2
• Project 3

If I chose "Project 1", then the list of notes shows all notes in this category/folder/group recursively:

• Introduction
• Open questions
• Sub-Project 1A
• Note 1
• Note 2
• Note 3
• Sub-Project 2A
• Note 1
• Note 2
• Note 3

[ThomasDaheim]

@korelstar Using formatting/coloring/... instead of indenting seems to be good idea!

@brantje : I have seen your method "Delete a note but keep the entity in db". That sounds like "archiviging", right? For file based notes it would mean to move them into a group "deleted" or similar?

[brantje]

@ThomasDaheim Afaik, when you delete a file using the files app it isn't deleted first. It gets a deleted flag, then under deleted files, you can completely remove the file.

[Fmstrat]

My suggestion: Implement groups, then convert to tags.

We've already got group functionality working, and this allows me to continue to focus on the mobile app. If we switch over to tags in the future, we can update users "groups" (which would be 1 per note) to the first "tag" when the upgrade occurs.

Prior to this happening, I could update the mobile app to check for tags/groups in the API response, and format accordingly, then phase out groups.