Aaron Parecki

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:

• Channels
• Retrieve the list of channels

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.