Sofie: The Modern TV News Studio Automation System (OpenAPI)

Provides a REST http interface into Sofie using the OpenAPI specification. The ability to auto-generate a typescript client is also provided.

About API stability

The Sofie OpenAPI makes attempts to avoid breaking changes. However, such changes are sometimes necessary. Therefore, this API intends to guarantee how the API will change in a breaking way, rather than how often.

The API definition itself will follow semver, where v1.0 is compatible with v1.1, v1.2, etc. Inside of Sofie Core, however, multiple versions will not be supported.

• When a non-breaking change has been made in the API, the minor version will be bumped. The old route (/api/v1.0) will now redirect to the new one (/api/v1.1) when v1.1 is the latest version of the API. Later, when v1.2 becomes available, /api/v1.0 will redirect to /api/v1.2 and so on
• When a breaking change has been made in the API, the major version will be bumped. The new route /api/v2.0 will now be implemented in Core, and all old routes (/api/v1.0, /api/v1.1 etc) will return the status code 410 (Gone).

The current version of the API is always available on /api/latest which will redirect to the most recent version (e.g. /api/v1.0).

How to use

How to write an external application that talks to Sofie

By using the OpenAPI-definitions when talking to Sofie, you can be confident that your application is compatible with Sofie, and that any Breaking Changes will be documented

npm install @sofie-automation/openapi

import { Configuration, PlaylistsApi, ResponseError, API_VERSION } from '@sofie-automation/openapi'

const config = new Configuration({
	basePath: `http://mysofie:3000/api/${API_VERSION}`,
})

const sofieVersion = await sofieApi.index()
if (sofieVersion.status !== 200) throw new Error('Bad initial response code')
// Check Sofie version:
console.log(`Talking to Sofie version ${sofieVersion.result.version}`)

const playlists = await playlistsApi.playlists()

const firstPlaylist = playlists.result[0]
if (!firstPlaylist) throw new Error('No playlists found')

await playlistsApi.activate({
	playlistId: firstPlaylist._id,
	activateRequest: { rehearsal: true },
})

For developers

This package requires you to install Java, a build of the opensource OpenJDK is recommended.

This package specifies the structure of Sofie's API. In future it is intended that this package be used to auto-generate a server that will be consumed by Sofie Core and integrated with calls to Sofie methods. However, for now the implementation of this specification within Core is a manual process as Core uses Koa as its web server framework, which has limited support for autogenerated implementations.

Implementation of changes to this package should be done inside of /meteor/server/api/rest/api.ts.

Breaking changes

This package contains API definitions that are intended to be STABLE. When making changes to these, you should take extra care to try to avoid any breaking changes. Where breaking changes are necessary, please open an issue to announce the breaking change.

Any breaking changes should result in a major version bump in /packages/openapi/api/actions.yaml. The API version will also need to be updated in /index.ts, as the version string is not exported by the OpenAPI code generator.

Generate stuff

yarn gendocs # Generate HTML-documentation
yarn genclient:ts # Generate client Typescript definitions
yarn genclient:rs # Generate client Rust definitions

Run unit tests

You can run against a mock server by running yarn unit. This mock way of running tests helps to verify that the autogenerated client can talk to the server, and that the examples provided in the OpenAPI specification are sensible and return sensible values.

Tests can also be run against a real Sofie system. This requires a bit of setup, you will need:

• Some peripheral devices (e.g. Playout Gateway) attached to a studio.
• Some blueprints uploaded to Sofie (any blueprints will work), with the System blueprint assigned and migrations run for your blueprints.
• Some playlists imported into Sofie (from any data source) with at least one Segment and at least two Parts.

You can then run tests against Sofie with SERVER_TYPE=SOFIE yarn unit:no-server. By default the tests will run against http://localhost:3000/api/v1.0, the server to run against can be changed with the SERVER_URL environment variable.