I'm implementing a draft of this in Aperture right now. Here is the current API.
Every entry now includes a unique system ID, meant for internal identification of the item (not global identification). This is returned in the timeline response as the parameter _id
, and there is now also _is_read
. For example:
{
"items": [
{
"type": "entry",
"url": "http://example.com/100",
...
"_id": "41003",
"_is_read": false
]
}
These new _id
values are meant to be opaque to clients, and must always be a string. Some servers will likely use integer database IDs, but other servers may use other string identifiers for entries depending on the implementation.
Retrieving the list of channels now also includes the number of unread entries in the channel:
{
"channels": [
{
"uid": "notifications",
"name": "Notifications",
"unread": 0
},
{
"uid": "YPGiUrZjNM36LNdpFy7eSzJE7o2aK82z",
"name": "IndieWeb",
"unread": 7
}
]
}
To mark an individual entry as read:
action=timeline
channel=example
method=mark_read
entry=1234
To mark multiple entires as read:
action=timeline
channel=example
method=mark_read
entry[]=1234
entry[]=5678
Both of the above also work with method=mark_unread
.
To mark an entry read as well as everything before it:
action=timeline
channel=example
method=mark_read
last_read_entry=1234
This is to address the use case of streams, where you really only care about knowing where in the stream you've scrolled to and whether there are any new entries since then.
This is mostly inspired by the Feedly Markers API Mark one or more articles as read and Mark a feed as read
Here is a diff of the changes.
The main differences can be read here:
aaronpk@aaronparecki ~/Code: curl -I https://ascraeus.org/article/websub-part-ii-aperture HTTP/1.1 200 OK Server: nginx Date: Sun, 11 Feb 2018 19:01:10 GMT Content-Type: text/html; charset=utf-8 Content-Length: 55151 Last-Modified: Sun, 11 Feb 2018 18:53:48 GMT Connection: keep-alive Keep-Alive: timeout=10 Vary: Accept-Encoding ETag: "5a80913c-d76f" Cache-Control: max-age=0 Accept-Ranges: bytes
Some silo examples of "home" vs "notifications":
and of course more on the wiki
Some discussion from IRC about whether hardcoding a "home" channel even makes sense in the first place.