API: allow requesting notes list in chunks

[korelstar]

see nextcloud/notes-android#761

• add new request parameter chunkSize and chunkCursor, send HTTP header X-Notes-Chunk-Cursor
• documentation
• tests

[korelstar]

@stefan-niedermann Would you have a look on this? I just added the documentation. Please check if the docs are understandable and if the functionality is as expected/desired.

[stefan-niedermann]

Yeah, i think i got it. But i expected to retrieve information about the totalCount when querying the notes list in chunks. Maybe this should he added as a response header when the chunkSize parameter is set?

I planned to show a progress bar (at some point in the future) at least when importing the account the very first time and i have a feeling that this requirement would fit to this PR - information about the total notes count would be necessary though.

What do you think?

Otherwise the documentation is understandable ✅

[korelstar]

I'm fine with such an addition. But let's clarify what is exactly needed and what can be provided. If you do a full import, the total notes count is interesting. However, if you combine the parameters chunkSize and chunkCursor with pruneBefore, the total notes count is misleading (since the total number of transferred notes is not equal to the total number of notes). Therefore, I think a "number of remaining notes" would be more general.

Proposal: if the current response is not the last response, the additional HTTP header X-Notes-Chunk-Pending is set to the number of remaining notes.

What do you think about this approach?

[stefan-niedermann]

Fine with it this definition ✅

One more thing regarding the wording: I am personally used to the term batch in this context instead of chunk - i am fine with keep naming the parameters chunkXXX, just wanted to note it in case you struggled with the naming, too.

[korelstar]

Wording is never easy. I think "batch" is more from the client processing perspective. But since REST is about resources and data, I think "chunk" fits better.

I'm finished now. If there is no protest, I will merge it in the next days.