Shelves — collections, folders and favourites

Three things that look similar and are not. Two belong to a learner; one belongs to an educator.

Collections

A learner's private shelves of articles and images. Not questions.

Each collection has a title and remembers when it was last used. Every collection is private to its owner, and the API says so on every row.

GET /collections/for-article/{id} and GET /collections/for-image/{id} ask the reverse question — which of my collections already hold this — so the bookmark icon on an article or a figure can be drawn filled or hollow without loading every collection.

Favourites

A question is marked, not saved. favorites is a plain (user_id, question_id) row and the endpoints are the three you would expect.

This is what the session builder's state=bookmarked filter reads.

The split is deliberate: an article is a thing you come back to and read again, so it goes on a shelf. A question is a thing you want to meet again in a session, so it gets a mark that the builder can filter on.

Folders — an educator's tool

Not learner-facing.

A folder is a named, hand-picked set of questions that a permission grant can point at, because the category tree cannot express "these specific forty questions".

• Anyone with editorial access can create a folder and add questions they already manage.
• Only a moderator can grant folder access to somebody else.
• Only the folder's owner or a moderator can change what is in it — otherwise the holder of a folder grant could widen their own grant by adding to the folder.

See Grants.