Atom Feeds

Atom Syndication

We use Atom Syndication to notify our clients about resource updates on our servers. Clients can poll the syndication feed periodically for updates, and once updates are available, the client can request the files from our servers. This is a much superior approach to repeatedly requesting the same files behind known URLs. There are also cases where the resource URLs are not easily otherwise known to clients when new resources are constantly being created. We recommend that our clients use the Atom feeder almost exclusively to be notified about updates on our servers.

newerThan

The newerThan parameter specifies that only feeds that have been updated after a specific date/time should be returned. If not specified, no filtering based on last update date is done. Note that dates are converted to our local time when parsed, so timezones are optional. An invalid feed parameter will result in a response with an error message and an HTTP status code of 400.

Icon

Please note that the newerThan parameter actually does a >= comparison when finding new feeds; this is because originally the most specific unit of measurement in a timestamp was a second, and feeds could potentially update at any time within a second. This has since been updated to include additional precision (4 places after the second) but it was decided that the parameter would remain inclusive allowing customers to remain unaffected.

The newerThan parameter must conform to the following pattern:

yyyy-MM-dd'T'HH:mm:ss.ffff
 yyyy-MM-dd'T'HH:mm:ss.ffffzzz

For example,

2007-06-29T14:31:41.1384
 2007-06-29T14:31:41.1384-3:00
newerThan best practices

We recommend using the value of the previous Atom response's <feed>/<updated> element as the value of the newerThan parameter for your next request.

For example, if you make the following request:

http://xml.sportsdirectinc.com/Atom?feed=/mlb/livescores&newerThan=2013-01-29T12:03:02.6567-04:00

The response will contain an <updated> element:

<feed xmlns="http://www.w3.org/2005/Atom">
     <title>Feed Index</title>
     <link href="http://xml.sportsdirectinc.com/Atom?feed=/baseball&amp;newerThan=2013-01-29T12:03:02.6567-04:00"/>
     <updated>2013-01-29T12:04:02.8112-04:00</updated>
     ...
 </feed>

Your next Atom request should look like this:

http://xml.sportsdirectinc.com/Atom?feed=/mlb/livescores&newerThan=2013-01-29T12:04:02.8112-04:00

Repeat this for each Atom response and next request.  

This should guarantee that you will never miss an updated feed.  However, as mentioned above, the newerThan parameter actually does a >= time comparison for updated feeds, so you will potentially end up getting the last updated feed again in your next request.  You can prevent this by adding a millisecond to the timestamp before using it in your next Atom request, but that will introduce a the potential to miss a feed if it updates < 1ms since your last Atom request.

maxCount

The maxCount parameter specifies the maximum number of feeds to be returned. If not specified, the default value of 5000 is used. An invalid parameter will result in a response with an error message and an HTTP status code of 400.

The maxCount parameter must be an integer.

order

The order parameter specifics the order in which the feeds will be returned. Valid parameters are 'asc' and 'desc'. If not specified, the default order will be desc. An invalid parameter will result in a response with an error message and an HTTP status code of 400.