Fixtures Push v2
- Raiko Pajur
Table of Contents
Description
Fixtures Push API v2 is a pub/sub or message queue mechanism for distributing updates in real time. The produced contracts are described in the Read Data Points section of each document under the Domain Entities document.
Fixture push v2 uses the same contracts as Fixtures API v2, thus the API Swagger is also relevant for the push users to get a good understanding of the models they need. If going for the swagger take the /GET methods and see all “{Entity}ResponseModel” - e.g. FixtureResponseModel, CompetitionResponseModel etc.
Architecture
The Fixtures Push API v2 has a simple architecture that listens for updates made in the Fixtures platform and then publishes them to a third-party real-time provider called Ably for consumption from the subscribers/consumers of the specific channels/queue.
Ably basically provide 2 options for the consumption of the messages.
Pub/Sub
Read more about it here: https://ably.com/docs/key-concepts
Firehose Message queue
Read more about it here: https://ably.com/docs/general/firehose
How to choose between both options
Pub/Sub is less fault tolerant, it only has 2 minutes of a window to keep to messages in client is not listening - the good news is that what is missed can be from ably history api up to 72h.
Pub/Sub. Getting what is missed from the history API makes the overall integration a bit more complex
Pub/Sub. Another option to get what is missed to bootstrap from Fixtures API v2
Pub/Sub requires the client to use the whole channel to subscribe to e.g. Fixtures.10.19 - this subscribes to football fixtures only for the Champions league
Firehose is fault tolerant by design as provide mechanisms to ensure reliable delivery, even in the presence of failures or intermittent connectivity issues
Firehose requires provisioning of infrastructure on the client which is connected by the Genius Sports team - however, this makes the solution more costly
Firehose can have wildcards on a subscription base thus having an integration Fixtures.10.* for all football fixtures, or even for all fixtures - Fixtures.*.*
Furthermore, this feature can have the significant benefit of reducing the complexity on the client by also supporting regex expressions, so if we assume that the client is interested only in a few specific entities for some concrete sports it can be easily achieved - (Competitions|Fixtures).(10|17).* will account for all competition and fixtures entities for Football and American Football.
Channels
The table below show all the channels to which a consumer can be subscribed and what is the granularity. Next to the name is a link where the contract for the changes could be found.
Channel name | Contract published | Description |
|---|---|---|
Localities | What is Locality? The locality entity has different meaning in different context:
| |
Organizations | An Organization is representation of a real-life organization like the “NCAA” in the USA. It groups multiple Competitions within multiple Sports. | |
Venues | The venue entity defines different things in different context:
| |
Persons | Person is a representation of a real-life person | |
Players.{sportId} | For this channel the consumer can subscribe directly to players which are part of specific sport by simply specifying the id of the sport in the channel’s name. e.g.: If you only want Tennis Players you can specify channel name: | |
Teams.{sportId} | For this channel the consumer can subscribe directly to teams which are part of specific sport by simply specifying the id of the sport in the channel’s name. e.g.: If you only want Football Teams you can specify channel name: | |
Doubles.{sportId} | For this channel the consumer can subscribe directly to doubles which are part of specific sport by simply specifying the id of the sport in the channel’s name. e.g.: If you only want Tennis Doubles you can specify channel name: | |
Contracts.{sportId}.{competitorId} | For this channel the consumer can subscribe directly to contracts which are part of specific sport and attached to specific competitor by simply specifying the id of the sport and the id of the competitor in the channel’s name. e.g.: If you only want Football Contracts for Barcelona you can specify channel name: | |
Competitions.{sportId}.{competitionId} | For this channel the consumer can subscribe directly to competitions which are part of specific sport by simply specifying the id of the sport and the competition id in the channel’s name. e.g.: If you only want Football Champions League Competition you can specify channel name: | |
Seasons.{sportId}.{competitionId} | For this channel the consumer can subscribe directly to seasons which are part of specific sport and specific competition by simply specifying the id of the sport and the competition id in the channel’s name. e.g.: If you only want Football Champions League Seasons you can specify channel name: | |
Rounds.{sportId}.{competitionId} | For this channel the consumer can subscribe directly to rounds which are part of specific sport and specific competition by simply specifying the id of the sport and the competition id in the channel’s name. e.g.: If you only want Football Champions League Rounds you can specify channel name: | |
Fixtures.{sportId}.{competitionId} | For this channel the consumer can subscribe directly to fixtures which are part of specific sport and specific competition by simply specifying the id of the sport and the competition id in the channel’s name. e.g.: If you only want Football Champions League Fixtures you can specify channel name: | |
SeasonCompetitors.{sportId}.{competitionId} | For this channel the consumer can subscribe directly to season competitors which are part of specific sport and specific competition by simply specifying the id of the sport and the competition id in the channel’s name. e.g.: If you only want Football Champions League Season Competitors you can specify channel name: | |
RoundCompetitors.{sportId}.{competitionId} | For this channel the consumer can subscribe directly to round competitors which are part of specific sport and specific competition by simply specifying the id of the sport and the competition id in the channel’s name. e.g.: If you only want Football Champions League Round Competitors you can specify channel name: |