Differences

This shows you the differences between two versions of the page.

--- software:api:start [2019/04/04 09:20] – created henrik
+++ software:api:start [2024/10/02 07:47] (current) – external edit 127.0.0.1
@@ Line 3: / Line 3: @@
 ====== API ======
 {{indexmenu>:software:api|nsort msort}}
+==== General ====
+When on the same local network as the master timing computer, the built-in web server can be used to access results data live from the software.
+This can for instance be useful for TV production, custom big screen displays etc.
+The basic endpoint is the same as the regular web interface/commentator display (for example http://localhost). All requests are made using GET requests to the specific endpoints, with any parameters added as query string parameters. The response will be given in JSON format.
+==== Endpoints ====
+All endpoints should be prefixed with **/api/1.1**. Example: http://localhost/api/1.1/event/races
+^ Endpoint ^ Parameters  ^ Description  |
+| /event/races     | None         | List all races |
+| /event/waves     | None         | List all waves |
+| /timing/locations     | None         | List all timing locations |
+| /timing/points | None         | List all timing points |
+| /timing/raceclock | race_id (required)      | Get the current race clock and gun start time of a given race |
+| /results/toplist | race_id (required), \\ page, page_size       | List all finishers of the given race, in position order |
+| /results/toplistforpoint | race_id (required), \\ point_id (required),\\ gender (optional), \\ page, page_size       | List all participants, in position order for a specific timing point |
+| /results/latest | point_id, \\ location_id, \\ page, page_size       | List the most recent passes of either a specific timing point or timing location (one of the is required ) |
+| /results/list | race_id, \\ racenum, \\ search, \\ page, page_size       | List all results in the event, regardless of finish status. Optional filtering on race, race number or text search |
+| /results/leaders | race_id (required), \\ gender (optional), \\ page_size       | Show the leaderboard of a specific race, optionally filtered by gender |
+| /results/participant | race_id (optional), \\ result_id (optional) \\ racenum (optional)       | Get the result of a single participant, including split times. At least one of result_id or racenum should be specified. race_id can be used to distinguish if multiple participants have the same race number.  |
+Default values if not set: page =1,  page_size = 50.
+=== WebSocket push ===
+If is possible to get pushed some basic events via a WebSocket connection.
+It is important to note that WebSockets are not supported via a BBT Extender connection.
+The endpoint to register and receive events is:
+**/api/1.1/push?events=xxx**   (xxx is a comma-seperated list of one or more event types to subscribe for)
+The events will be pushed whenever they occur in JSON format. They all have a basic structure indicating the event type. Depending on the event, more data might be included.
+{"event":"xxx"}
+^ Event type ^  Description  |
+| results     | Every time a result is recomputed or changed, this will trigger an event. The event will include the basics of the result (id, race, finish time etc). |
+| eventdata     | Some event data was added or modified. This might be races, waves, settings, timing setup etc. The event will currently not include any detail about the change. |