API

You can register to receive real-time notifications of new entries for dailymile users using the PubSubHubbub protocol. We provide Atom feeds for all users' entries that are marked up with Activity Streams. Getting notified via PubSubHubbub is a much better way to track users than constantly polling their entries feed.

Firehose

The dailymile firehose is a feed containing all public entries. It's available to be consumed in real-time via PubSubHubbub using the following topic URL:

  http://www.dailymile.com/entries.atom
  

Discovery of User Feeds

Every user profile page (e.g. http://www.dailymile.com/people/ben) on dailymile allows discovery of its entries feed URL via the <link> tag in the header with the type of application/atom+xml. Here's an example PubSubHubbub topic URL for a user ben's entries that can be subscribed to. You can open it up in your browser to see what the feed looks like:

  http://www.dailymile.com/people/ben/entries.atom
  

Subscribing to updates

Once you have the topic URL for a user you can begin receiving real-time updates for by subscribing at that feed's hub. You can find URL to the hub in the feed on the <link> element with a rel value of "hub".

  <feed xmlns="http://www.w3.org/2005/Atom">
    <link rel="hub" href="http://pubsubhubbub.appspot.com/" />
    <entry>
      <!-- entry data -->
    </entry>
  </feed>
  

Instructions on how to do this are outlined in the Subscribing and Unsubscribing section of the PubSubHubbub spec.

Subscription request

Send a subscription request to the hub with the feed you'd like to receive real-time updates for. You'll include a callback URL to let the hub know where updates should be sent. Here's how we'd tell the hub we'd like to subscribe to the above entries feed and receive notifications of new entries at http://example.com/callback:

  POST / HTTP/1.1
  Host: pubsubhubbub.appspot.com
  Content-Type: application/x-www-form-urlencoded
  
  hub.mode=subscribe&
  hub.topic=http%3A%2F%2Fwww.dailymile.com%2Fpeople%2Fben%2Fentries.atom&
  hub.callback=http%3A%2F%2Fexample.com%2Fcallback&
  hub.verify=async
  

After subscribing, the hub will send a verification request to your app's callback URL. (You can read more here.) To confirm the subscription, your app responds with an HTTP success status code (2xx) that contains the hub.challenge parameter provided in the hub's verification request in the request body. The hub may continue to send verification requests from time to time to ensure that your app still wishes to receive updates. If at any time you no longer want these receive updates, just respond with a 404.

Receiving updates

Once subscribed, the hub will start POSTing your callback URL with the Atom entries from the user you subscribed to. Your application must respond with an HTTP success status code (2xx) so that the hub knows you've received their updates.