Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
105 lines (74 sloc) 4.92 KB

Overview

Authenticated calls to Tweet Marker use OAuth Echo to verify a user's account, just like when posting an image to Twitpic. If you are already doing image upload with OAuth Echo, you may be able to reuse the headers you create exactly, just pass them to a different URL.

X-Verify-Credentials-Authorization should be constructed in the usual way with secret keys, etc. More info about OAuth Echo is available here: http://dev.twitter.com/pages/oauth_echo

X-Auth-Service-Provider should be: https://api.twitter.com/1.1/account/verify_credentials.json

Set last-read marker

To mark a tweet, send its status ID to the server. This should usually be the tweet that is currently visible at the top of your view. If scrolled, this might not be the most recent tweet. Other clients will then refresh and scroll this saved tweet (if it's found) so that it's also visible at the top of the view.

The "collection" parameter should be one of these: timeline, mentions, messages (for DMs), favorites, lists.id, searches.id. But it can be anything, if you have special groups of tweets that you want to sync.

POST /v2/lastread?api_key=yourkey&username=manton

{
	"timeline":  {
		"id": "123456",
		"marked_at": "Sun Mar 25 16:32:54 +0000 2012"
	},
	"mentions":  {
		"id": "123456",
		"marked_at": "Sun Mar 25 16:32:54 +0000 2012"
	}
}

For the POST, only the "id" value (tweet status ID) and one or more collection keys is required. The "marked_at" is a new timestamp which can be set by the client and will be preserved on the server and returned in the GET. It's optional, and there's also an "updated_at" that is the timestamp of when the record was actually saved. Usually these will be within a second or so, depending on how long the request is. If a client does not include a "marked_at" value, then the server will automatically set it to match "updated_at".

The simplest POST with only required values:

POST /v2/lastread?api_key=yourkey&username=manton

{
	"timeline":  {
		"id": "123456"
	}
}

The "version" field is incremented on the server every time the record is saved. You can use this (or the timestamps) to determine if the record has been changed by another client. If before sending to the server the version was "2", then you can expect it will be "3" the next time if no other client has updated the value in the meantime. If any other client has changed it, it will be "4" or greater.

If you want to request more than one collection in a single GET request, include multiple "collection" params as in the example above. No collection name is used from the URL in a POST since it's now in the JSON body as hash keys.

The 4 possible values for each collection for completeness (same as first example above):

id: read/write (required)
marked_at: read/write (optional)
updated_at: read-only
version: read-only

Get last-read marker

More than one marker can be retrieved at once by including multiple collection parameters on the URL.

GET /v2/lastread?api_key=yourkey&username=manton&collection=timeline&collection=mentions

{
	"timeline":  {
		"id": "123456",
		"updated_at": "Sun Mar 25 16:32:54 +0000 2012",
		"marked_at": "Sun Mar 25 16:32:54 +0000 2012",
		"version": 15,
		"username": "manton"
	},
	"mentions":  {
		"id": "123456",
		"updated_at": "Sun Mar 25 16:32:54 +0000 2012",
		"marked_at": "Sun Mar 25 16:32:54 +0000 2012",
		"version": 42,
		"username": "manton"
	}
}

Read state for direct messages

GET /v2/messages?api_key=yourkey&username=manton

POST /v2/messages?api_key=yourkey&username=manton

{
	"read": [
		"123456",
		"120000",
		"5000"
	]
}

By default returns highest 500 message IDs. Optional parameters: count and max_id. If max_id is included, IDs will start with the first that is equal to or lower than max_id.

To set messages as read, POST with the same structured JSON body. You can include all your read IDs, just the latest ones, or a single ID that was just marked as read. Tweet Marker will always merge your POST contents with the existing server list of read messages.

Both get and set read messages calls are protected by authentication, which Tweet Marker handles in the background so that it doesn't slow down requests. If you request the read messages and your app hasn't yet sent a request to Tweet Marker, you may get an empty response on the first attempt.

Authentication

GET /v2/auth?api_key=yourkey&username=manton

Most of the time, authentication is via OAuth Echo and completely automatic. However, if you've never called Tweet Marker from your app on a given device and Twitter account, you can make a simple request to this auth URL to give Tweet Marker a chance to verify and cache the user information it needs. This is particularly helpful if you plan to immediately request a list of read messages.

There's no reason to call this more often than once per account, per device. It is optional.