search

appdotnet / api-spec

App.net API Documentation is on the web at https://developers.app.net. Source for these docs is in the new-docs branch here. Please use the issue tracker and submit pull requests! Help us build the real-time social service where users and developers come first, not advertisers.
https://developers.app.net
950 stars 98 forks source link

Document more clearly how stream markers are used with the Messaging API #257

Open mattflaschen opened 11 years ago

mattflaschen commented 11 years ago

The Markers documentation for messaging is unclear. It says:

"The unread state of each Channel is tracked by a stream marker like those used for Posts. We suggest you do not advance a channel stream marker in reverse. When requested with a specific user token, each Channel exposes whether it contains a newer Message than the current marker position for the purpose of displaying an ‘unread’ indicator."

which is fine as an intro, but there are no links to specific docs. The other two logical places to look are:

  1. Stream Markers. This has no message of Message anywhere. Since you are drawing a distinction between the two, you need to explicitly mention Message everywhere, even if it is to say "Post or Message". It says, "The current stream marker will be included in the response envelope from any stream that returns Posts." which does not make sense for Channels/Messages.
  2. The Channel docs have has_unread, which is part of the picture. But there is no "marker" key, and no information about how to advance it. The Channel endpoints have nothing explicitly about markers. I assume I use http://developers.app.net/docs/resources/stream-marker/#update-a-stream-marker , but it's not clear.