16-jan-23
• Support time_start in / CreateInstantGame endpoint: This feature will allow the processing of the video with the with the following logic:
- If there is not information provided about the if the field time_start is omitted from the request, the processing -of the video starts from the very beginning of the video. (This part is unchanged)
- if the request is submitted more than 10mn before kickoff, the deployment of processing pipeline is scheduled. Which means that the calibration refinement will be triggered as well
- otherwise, if game order is submitted between 5mn and 10 min before kickoff, the processing pipeline will be deployed right away to be ready at kickoff.
- otherwise, the processing pipeline is not going to be ready on time. In this scenario the pipeline will start the processing 30 seconds before kickoff. There will be a few additional constraints in that case: streams are required in the game order and can’t be submitted later, otherwise the game order is rejected streams must be “seekable”, which means old segments of the video are accessible. This can’t apply to “true” live streaming protocols such as RTSP and SRT
• New endpoint GameStatusCodes: This endpoint will allow to retrieve the full list of error codes and descriptions. The StatusCodes endpoint explains the status_code in the Games model.
• Support of 3-digit player numbers (from 0 to 999, formerly only supported from 1 to 99). This change impacts: TeamAwayLineup TeamAwayPlayers TeamHoimeLineup TeamHomePlayers Events Tracks
CHANGELOG
• Specify semantic identification for IDs as uuid. Applies to venue, phase and game IDs.
• Remove obsolete properties from the Game model: team_home_formation, team_away_formation, team_home_logo and team_away_logo.
• Remove obsolete properties from the Phase model: time_start, time_end, team_home_redcards, team_home_substitutions, team_home_kickoff, team_home_is_left, team_away_redcards andteam_away_substitutions.
• Documentation readability improvement: regroup endpoints in 4 categories Games, Venues, Phases and User.
NOTES
We recommend our users to use the version 4 of this API, which is now generally available. API Version 3 is still available, but from now on new features will be shipped in the version 4 only.
BREAKING CHANGES
• From API v4, authentication relies on JWT tokens. Therefore it’s now required to use the corresponding Bearer schema.
• Remove _ in endpoints GET|POST https://api.signality.com/v3/games/{id}/_streams, so it’s now https://api.signality.com/v4/games/{id}/streams
• API v4 proposes a different workflow to submit new calibrations. In API v3 it was required to first create a new calibration before submitting jpeg images, one image at a time. In API v4, there’s a single endpoint to submit images on new calibration requests using multipart/form-data. See https://help.signality.com/api/#operation/VenueCalibrationController.postCalibrationWithImages for details
IMPROVEMENTS
• While previous version relied on swagger, OpenAPI v3 is now supported by default. That should considerably improve the readibility and compliance of the specifications.
• Starting from version 4.0.0, the API service supports semantic versioning using url prefix, such as /v4.0.0/. Note that /v4/ would always redirect towards the most recent version of the API.
NEW FEATURES
• Phase model is accessible using its number property, in addition to phaseId. Example: GET /v4.0.0/games/<GAME_ID>/phases/1.
• For each data channel, tracks, events and stats, GET operations returned additional metadata in the HTTP header:
--- `ContentLength`: indicate the length of the body in bytes
--- `LastModified`: when data was last modified
--- `Version`: to indicate what's the version format of the data
--- `Stage`: `live` or `final`, for `tracks` channel only.
Those metadata fields can also be retrieved independently of the data itself, by using HEAD operations on the same endpoints, aka. HEAD https://api.signality.com/v4.0.0/games/{gameId}/phases/{phaseIdOrNumber}/tracks
-- Add team_home_colors and team_away_colors properties to the Game model, an array of strings describing team jersey colors in hexadecimal notation
-- /instant, /request and /plan endpoints support team_home_colors and team_away_colors new properties
-- new property status_code in Game model indicating the outcome (more detailed documentation will follow) :
- 1XX: deployment failure, aka. lack of ressources
- 2XX: processing failure, aka. missing streams at kickoff, crash etc.
- 3XX: data innacuracy, aka. calibration being off, missing substitution etc.
-- new property deployment_state in Game model to indicate the state of the processing pipeline:
"deployment_state": {
"default": "WaitingForValidation",
"enum": [
"WaitingForValidation",
"Manual",
"Planned",
"Deploying",
"Deployed",
"Destroying",
"Destroyed"
],
"description": "state of processing pipeline",
"type": "string"
}
-- GET venues/{id}/calibrations to list calibrations of a venue
-- GET venues/{id}/calibrations/{fk} to get a specific calibration
-- POST venues/{id}/calibrations to create a new calibration
-- POST venues/{id}/calibrations/{fk}/image/{label} to upload a new image for an existing calibration
-- endpoints /plan, /instant and /request support a new property calibrationId in request payload. If not specified, the most recent calibration is used. For a calibration to be valid, calibrationId must refer to an existing calibration of the venue and the calibration must have at least one element in _views. If condition is not met, an error 400 is returned.
-- data_level type is now integer in openapi documentation
-- document request body for users/login
-- change endpoint to create a new venue: POST venues (instead of POST venues/new) to match with naming convention
-- data_level is now exposed in Game model
see [Data levels](/concepts/levels/) for details
-- new property home_team_is_left in Phase model
true if home team is located on the left side of the pitch in regard to central camera’s positions.
-- new endpoint to create Venues /venues/new
-- new endpoint to submit still images from camera /venues/{id}/image/{label}
-- initial API release