Develop

Message Broker 2.0

GET /events
GET /filtered-events
WebSocket /event-stream

GET /events

Allows authenticated customers to receive JSON messages in near realtime which contain race data from Swedish Trotting Association and Swedish Gallop.

The /events API emulates optional push technology by using long polling. The client polls the server requesting the needed information. If the data is available that is matching the criteria, it is returned immediately. If the data is not available at the moment, the server holds the request open until new data of durable channels is available. Once available, the server responds and sends the new information. When the client receives the information, it immediately sends another request, and the operation is repeated.

The server will not wait indefinitely for new information. If no new information arrives within a set time limit, the server will issue an empty response with status 204. Following this, the client should immediately make a new request to continue waiting for information.

The customers can get back-dated data if needed, or for that matter, ask for the same data again.

Internally, Message Broker receives messages on different channels. All the durable messages are delivered on the same endpoint, but you will only receive messages from the channels that are included in your subscription agreement.

HTTP request

GET https://api.travsport.se/customerapi/events

Header Parameters

authorization (required) string - Bearer token. E.g.

Authorization: Bearer <AUTH_TOKEN>

GET Parameters

?lastEventId=<ID>&limit=<NUMBER>

• lastEventId (optional): The last event ID that the customer received earlier. The API will return the new events with IDs greater than this. The customer can pass 0 to start getting all the back-dated events available as of now. Or any previously received event’s ID to get all the events after that ID. This is an optional parameter. If not passed, the API will return just ONE event that is the latest event available in the customer’s subscription. If all the back-dated events are not required, but the customer wants to receive only the future events, lastEventId can be skipped and the API will return just the last event in the subscription with the highest eventId from where to go further. And if lastEventId is not passed, limit is also ignored (assumed to be 1).
• limit (optional): The maximum number of events to be returned by the server in a single response, if there are more available, the server will indicate. The value of limit is ignored (assumed to be 1) if lastEventId is not passed.
• The events of all the subscribed durable channels will be returned.

Request Validation

Requests to this endpoint are validated to ensure:

If the lastEventId parameter is passed, it is a number >= 0.

The optional parameter limit, if provided, is a number >= 0. If not passed, it defaults to a value configured in the server.

Response Types

Response body:

{
	"status": "success",
	"data": {
		"numberOfEvents": 0,
		"hasMore": true|false,
		"events": [
			{
				"channel": "CHANNEL",
				"date": "yyyy-mm-dd",
				"trackId": 0,
				"raceNr": 0,
				"startNr": 0,
				"payload": {
					<JSON_DATA>
				},
				"created_at": "2023-11-23T13:30:39.910Z",
				"eventId": 6
			},
			....
		]
	}
}

• status - Either success or fail
• data - Only in case of status = success - Data object
  • numberOfEvents - The number of events returned as part of this response
  • hasMore - If the server already has more events to be returned. Call again with last Event ID to get more
  • events - Events array
    • channel - Channel name
    • date - Event date
    • trackId - Optional. Track ID if any
    • raceNr - Optional. Race number
    • startNr - Optional. Start number
    • payload - Channel-specific event data
    • created_at - Event creation timestamp
    • eventId - This is the most important field. Remember the last event object’s this field’s value. Send that in the next request to receive events after this ID.
• message - Only in case of status = fail - Error details

GET /filtered-events

Allows authenticated users to retrieve a list of events filtered by specific criteria, including channel, date range, and optional parameters like track ID, race number, and start number.

HTTP Request

GET https://api.travsport.se/customerapi/filtered-events

Header Parameters

authorization (required) string - Bearer token. E.g.

Authorization: Bearer <AUTH_TOKEN>

GET Parameters

• channel (optional): The name of the channel. If provided, it must be one of the channels subscribed to by the user.
• startDate (optional): The start date for filtering events, formatted as YYYY-MM-DD.
• endDate (optional): The end date for filtering events, formatted as YYYY-MM-DD. If startDate and endDate both are provided, endDate should be greater than or equal to the startDate.
• limit (optional): The maximum number of events to be returned by the server in a single response.
• lastEventId (optional): If you want to continue from the last response onward, this represents the eventId of the last record of the events array you have received. If this is passed, it has to be a number and it will return the records with eventId greater than this and matching the given criteria.
• trackId (optional): A specific track ID.
• raceNr (optional): A specific race number.
• startNr (optional): A specific start number.

Example request with a full set of parameters:

GET https://api.travsport.se/customerapi/filtered-events?channel=RaceDayGallop&startDate=2024-01-01&endDate=2024-02-29&lastEventId=50&trackId=123&raceNr=123&startNr=123&limit=10

Request Validation

Requests to this endpoint are validated to ensure:

• The channel parameter, if passed, is one of the user’s subscribed channels. If not passed, server considers all the channels in subscription
• If passed, startDate and endDate are valid dates in YYYY-MM-DD format, with the start date being before or equal to the end date.
• Other optional parameters (lastEventId, limit, trackId, raceNr, and startNr) if provided, are expected to be numeric. The limit, if not passed, defaults to a value configured in the server.

Response Types

Response body:

Response body will be exactly the same as for the /events API described above.

WebSocket /event-stream

Allows authenticated customers to receive JSON messages in near realtime which contain race data from Swedish Trotting Association and Swedish Gallop.

The /event-stream WebSocket emulates push technology. The client connects to this web-socket endpoint once and the server will broadcast the transient channel events to all the connected clients who have subscribed to the channel for which the event is raised.

These messages won’t be repeated. Those are broadcasted only once and not stored anywhere.

In case the WebSocket gets disconnected, the customers have to reconnect and follow the same authentication process to continue receiving the messages.

WSS request

wss://api.travsport.se/customerapi/event-stream

Flow of operation:

1. The client connects over WebSocket
2. The Server will send a message:

   {
     "type": "Connection",
     "message": "Connection is established. Awaiting auth token within 10 seconds",
     "timestamp": "2023-11-30T12:19:54.179Z",
     "id": "f5adb4eb-a3ed-48c3-8ef2-5ac500fc5336"
   }
   

3. The client will have to send a plain text message with just the auth-token within the said number of seconds.
4. If the client fails to send the auth-token within the stipulated time, the server will respond with the following message and close the socket

   {
     "type": "AuthenticationError",
     "message": "Did not receive Auth token",
     "timestamp": "2023-11-30T12:20:04.181Z",
     "id": "f5adb4eb-a3ed-48c3-8ef2-5ac500fc5336"
   }
   

5. If the client sends an invalid auth-token within the stipulated time, the server will respond with the following message and close the socket

   {
     "type": "AuthenticationError",
     "message": "Invalid auth token",
     "timestamp": "2023-11-30T12:24:55.725Z",
     "id": "f02ce795-5a65-4527-9250-dcb35ac5d0a3"
   }
   

6. If the client sends a valid auth-token within the stipulated time, the server will respond with the following message, and from that point onward, it will broadcast the transient messages to this connected client. Before this point in time, even if the new transient messages are available, the server won’t broadcast those to the not-yet-authenticated clients

   {
     "type": "Authenticated",
     "message": "Connection is authenticated.",
     "timestamp": "2023-11-30T12:27:35.575Z",
     "id": "dae74b6d-8faf-4140-b15b-cc0ad37771d4"
   }
   

7. The transient messages will be broadcasted to the authenticated WebSockets in the following format:

   {
     "type": "Data",
     "data": {
       "channel": "<TRANSIENT-CHANNEL-NAME>",
       "date": "2023-11-06",
       "trackId": 123,
       "raceNr": 456,
       "startNr": 789,
       "payload": {
         .... Channel specific payload data
       }
     },
     "timestamp": "2023-11-30T12:29:19.236Z",
     "id": "dae74b6d-8faf-4140-b15b-cc0ad37771d4"
   }
   

8. Also, after a successful authentication, the websocket will receive a Ping message from the server every minute to make sure that the socket does not disconnect, even if there are no transient messages received from the server for a long time:

   {
     "type": "Ping",
     "timestamp": "2023-11-30T12:30:19.236Z",
     "id": "dae74b6d-8faf-4140-b15b-cc0ad37771d4"
   }
   

   This message will just need to be ignored by the customer.