Working with the Myriad Playout v5 and v6 REST API

Introduction

Myriad Playout v5 and v6 contain a powerful REST API system that allows you to remotely query information from Myriad as well as being able to send instructions TO Myriad to tell to do something.

The REST API system that Myriad uses is based on the OpenAPI project (https://www.openapis.org/) which provides an industry standard way to access the API. 

Before reading the rest of this article, you should make sure you are familiar with the concepts of using a REST API and using testing tools such as curl.

Enabling the OpenAPI REST interface in Myriad Playout

This information relates to both Myriad Playout v5 and v6. In the following screenshots, the lighter grey colour images are taken from Myriad v5 and the darker ones from Myriad v6

To enable the REST interface, login to Myriad Playout, then on the Settings Menu, click Application Settings then navigate to the Connections tab and look under the "HTTP Service Connection:" section

To make sure that the HTTP OpenAPI service is always available, select the "Always allow HTTP Service Connections....". If you will be accessing the API from another device, you should also click click the "Re-create firewall exceptions" button to make sure that the Windows Firewall has been correctly adjusted to allow remote connections.

Security note - Requiring an API Key

We strongly recommend that you leave both "Require an API Key for OpenAPI read Requests" "Require an API Key for OpenAPI write Requests" turned ON. The appropriate key must then be sent with every API request as an X-API-Key header. 

If you turned these off then the API is wide open and there are NO restrictions on the API commands that can be used. A malicious user could easily take full control of your database and do significant damage.  If you suspect that someone has gained access to the keys then you can click the Generate button to generate new random keys.

You can use the same key for both Read and Write requests if you prefer, but best security practice is to use separate different keys for read and write methods.

Finishing configuration

Click OK to save the settings, and you will be prompted to restart Myriad for the settings to take effect.

Testing the API

Once Myriad has restarted, go to the Help menu and select Documentation then Display OpenAPI REST information which will open a webpage that shows the available REST API documentation.

You may find this refers to the "Swagger" API - Swagger is an automatic documentation system used by OpenAPI compatible systems to present a standardised appearance for documentation:

The REST API methods are arranged into logical areas - for example Application, Commands, Database, Favourites and and so, and clicking on the header will expand that section and show you the available commands in that section. In the screenshot above you can see we have expanded the Application section, revealing the GetStatus, GetVersion and GetProfileName API Methods.

Important: Myriad Playout v5 has a wide variety of REST API Methods, but v6 has several additional methods and more will be added to v6 over time, so when consuming the API please check the Swagger page for whether the command you are using is available in the Version of Myriad you will be connecting to.

You should also carefully check the parameters AND return values of the API you are using as some of these are different between v5 and v6.

Example command:

We are going to use the Application/GetStatus command to query some basic information from the Myriad Playout REST API.

To do this, return to the Application Settings window above and copy the "Read requests". In our screenshot above it is "changemeC3865287567759903B2A32A6154CB1ED" but will be different for you.

At the top left of the Swagger webpage, enter your API key carefully and click the Explore button, then expand the "Application" section, then click on the /api/Application/GetStatus item, then finally click the "Try it out! button at the bottom of that section:

Your display should update, and if you scroll down the webpage you should see a new "Response Body" section showing you the result of your query which should look something like the below:

If you see a Response Code other than 200 then it's likely that you have entered the API key wrong, or have mixed up the read and write keys - this method is reading data, so we need the Read key, for other methods that make Myriad do some work - these are "write" methods so need the Write key.

As you can see from above, the response tells you a bit about the Myriad system including what mode the Media Engine is in, the name of the currently open station, even the current time on the system.

Each method will return different information, and in general are pretty self explanatory.

Testing from a Command line:

Scrolling backup the web page, underneath the "Try it out!" button you will see a "Curl" section and this shows you how to call that same method using the curl command line utility. Curl is commonly installed on Linux systems and comes built in to recent versions of Windows 10 and Windows 11 as well.

To run the same command as above but this time using the Curl command we can see we need to use:

curl -X GET --header 'Accept: application/json' --header 'X-API-Key: changemeC3865287567759903B2A32A6154CB1ED' 'http://localhost:9180/BrMyriadPlayout/v6/api/Application/GetStatus'

To understand the meaning of the above, please consult the system documentation for the version of Curl that comes with your operating system.

Conclusion

As you have seen, the REST API can be very easy to use, and the available commands range from simple to extremely powerful - for example /api/Qae/RequestTransfer can initiate the SmartTransfer system to move the running Log to another computer, whilst the /api/players commands give you total control over the media players on your system.

Because of the nature of the REST API, our normal Technical Support is only able to provide basic advice on using the REST API itself, you will need to be experienced in using REST APIs to get the best from the system.