Feed model
A complete snapshot of the content you can use now.
A 200 is a complete snapshot, not a page, patch or event stream. It has no pagination or continuation cursor.
| Field | Meaning |
|---|---|
fixtureId | Your integration’s fixture identifier; the NBA examples use game IDs. |
feedKey | The named feed for that fixture. Public samples use pulse. |
snapshotAt | Timestamp associated with the snapshot. Unfiltered live feeds use the latest commit time. Sample feeds use their bundled timestamp; replay has separate rules. |
items | Every currently consumable item for this response scope, in delivery order. |
Order and time
Items are ordered by the active revision’s publishedAt, newest first, then id ascending as a stable tie-break. This is delivery order. Use effectiveAt when placing an item on the fixture timeline.
| Item time | Meaning |
|---|---|
effectiveAt | The item’s logical fixture-timeline anchor. |
asOf | The information cutoff for the item. |
publishedAt | Publication time of this revision; determines delivery order. |
In the generated NBA samples, all three times are the play’s event time and represent example publication. Live publication need not occur at that same instant.
Revisions
A rewritten item keeps its id and original effectiveAt, and increments its positive integer revision. Replace the item with the new revision; do not append a duplicate. Its definitionVersion describes the shape of its content, independently of its revision. A distinct content item has a distinct ID.
Withdrawals
A withdrawn item is absent from the next successful snapshot. The read response does not include a withdrawal marker or reason. Remove local items that are no longer present. Do this only after a successful full response; a 404 or other error is not an empty snapshot.
Withdrawn items remain excluded even when replay parameters ask for earlier publications. Replay is not an archive of removed material.
Application state
- Retain the current snapshot and its ETag for one exact feed request.
- On
200, atomically replace them with the new snapshot and ETag. - On
304, keep them. - On an error, keep them while handling the error; show any resulting staleness appropriately.
Keep separate state for each client identity, fixture, feed and replay query. Reset state when changing that scope. See Item types for the generic envelope and nested content fields.
Action numbers and supporting values
Where a definition includes content.actionNumber, it is an integer, not a quoted number. NBA definitions use it to attach an item to a play. A definition without this field is excluded when atAction is requested.
NBA statistics carry a machine value, a presentation displayValue, an explicit scope and a statistic unit. Use these fields rather than inferring units or comparison scope from copy.
Entities and assets
Entities use id, kind and displayName. Assets use id, kind, href, mediaType and altText. Both definition versions share these shapes. Asset hrefs are URI references; the Portland examples use API-root paths that resolve against the API origin. Resolve paths without treating generated copy as HTML.