REST API Quick start guide
Below is the list of REST commands that you can send to OnTheAir CG Server or OnTheAir CG Designer. Here is an example of request that you can use in a simple browser. Type the following in the url field of any browser (including mobile devices) :
This will return a dictionary with the list of projects opened in a OnTheAir CG Server application, which should look like this:
[}
{
"status" : "Playing",
"elapsed" : "00:00:08",
"uniqueID" : "58A56C06-EBD8-450C-B5D3-662F25D1EAFE",
"duration" : "--:--:--",
"remaining" : "--:--:--",
"path" : "\/Applications\/OnTheAir CG 3\/Samples\/Projects\/AppleScript.cg3",
"displayMode" : "1080i 59.94"
},
{
"status" : "Stopped",
"elapsed" : "00:00:00",
"uniqueID" : "7B63AFB8-58F0-4B3F-AE3E-EC8B16FC8ADE",
"duration" : "00:00:10",
"remaining" : "00:00:10",
"path" : "\/Applications\/OnTheAir CG 3\/Samples\/Projects\/LowerThird.cg3",
"displayMode" : "1080i 50"
},
{
"status" : "Paused",
"elapsed" : "00:00:01",
"uniqueID" : "3C1B552C-F9DC-4691-8DE6-D57BF41775E8",
"duration" : "--:--:--",
"remaining" : "--:--:--",
"path" : "\/Applications\/OnTheAir CG 3\/Samples\/Projects\/AnalogClock2.cg3",
"displayMode" : "1080i 50"
},
]
About the authentication token
The general idea is that to see the status of a OnTheAir CG Server, get the list of projects, etc... you don't need to send a token. If you need to change something (start/stop playback, modify a project), then you need to use a token in your requests. Tokens are unique and only one token is valid at a time. So if another client request a token, your token will be revoked, and you will need to request a new token. The idea is that only one client at a time can do modifications in order to avoid conflicts. A token is valid for as long as it is not revoked by a new token request.
How to get a token ?
To get a token, you need to know the password of a OnTheAir CG Server (the default password is "1234"). A token is returned when you use the "unlock" request using the password of the OnTheAir CG Server you are connected to. Here is an example of request you can do to retrieve a token when used on the same computer with OnTheAir CG Server running (you may have to change the IP address and port number) :
Sending a request that requires a token
Once you have a valid token, you can send requests that require that token. Below is an example of request using a token to start playing project at index 1 (the index is 0 based, so this will start the second project starting from the top. It also means that at least 2 projects must be loaded in OnTheAir CG Server, otherwise it won't have anything to play:
If the token is incorrect, it should return this:
"success" : false,}
"error" : "not authenticated"
With a valid token it should return the following, confirming that it could start playing.
"success" : true}
You could also start a project by indicating its Unique ID (that you can retrieve as explained above). So this will be independent of its position in the list of projects which can vary :
If the token is correct, it should return the following and start the specified project.
"success" : true}
Projects
Unique id or index ?
Each project can be addressed using either its unique_id, or its index. The unique_id is the safest way to talk to a project as it will not change and remain unique. The index is the position of that project in the list of projects that are loaded in OnTheAir CG Server. It can change depending on the other projects that are loaded and ordered.
Basic GET request for projects
To return the list of projects that are opened on that OnTheAir CG Server. :
To return the description of a specific project :
Controlling projects
Note that when a project is opened in OnTheAir CG Server, still images and animated sequences are immediately buffered to the memory of Graphics card so projects are ready to play. You should then be careful when opening project that you still have enough memory on the Graphics card to open it. And you may need to close other projects. Videos are not buffered to the graphics card.
To open a project :
To close a project :
To start playing a project :
To pause a project :
To stop a project :
Items
Projects hold items. Items can be either a text, a shape, a ticker,...
Unique id or index ?
Each item can be addressed using either its unique_id, or its index. The unique_id is the safest way to talk to an item as it will not change and remain unique. The index is the position of that item in the OnTheAir CG project item's list (it's a zero-based order). It can change depending on the other projects that are loaded and ordered.
Basic GET request for items
To return the list of items of a project. Note that by default OnTheAir CG Server is set to only return the list of "published" items. If you want to see the complete list of items and modify them, you need to enable the option in OnTheAir CG Server to publish all items.
To return the description of a specific item:
Modifying items
To modify items you need to use the PUT method, and to use tokens, for example, the following request would modify the Text field of the item specified to "This is my Title", and set it as a visible item:
{
"text" : "This is my Title",
"hidden": true
}
Note that
- properties that are not sent remain unchanged.
- if at least one property is invalid, the whole modification will be ignored.
You can also modify multiple items at a time:
[
{
"uniqueID" : "C5A781D1-E2D6-4B3C-8F98-9F443E07C615",
"text" : "This is my Title",
"hidden" : true
},
{
"uniqueID" : "E5A0880C-8073-4782-AB20-BF75CF420126",
"text" : "This is my SubTitle"
},
{
"uniqueID" : "DC68D0E0-C367-4C68-8A2C-76A5F113A940",
"width" : 150,
"hidden" : false
}, ]
For more information
If you need more info or support about OnTheAir CG, you can find it on our support desk.