# AUTHENTICATION:

Depending on the chosen way of authentication two approaches can be differentiated for initial interaction with the Live API:

• API Key: API keys can be generated after the installation has been completed. Generating of API keys requires the use of an ID Token.
• ID Token: A request is made to the ioAuth service with POST /auth/authorize with an email and password being passed on. The ID Token from the response can be used for any following requests. Email and password are passed like so:

   {
        "password": "randpass",
        "email": "johndoe@mail.com"
    }

Identification with API Key requires passing of the x-api-key header; Endpoints using API Keys have a private/ prefix; Identification with an ID Token requires passing it via the Authentication header, endpoints using ID Token are not prefixed. As of now there is no difference between functioning of the endpoints regardless of the authentication method.

API KEYS: The following operations are supported: Getting a list of API Keys Information for a single API Key Create, edit, delete of an API Key Each API Key can be activated/deactivated

# REGIONS:

Listing of all supported regions is currently supported. For a region to be supported the Live service needs to be installed in it. Installation is in two stages:

• 1st Stage: The API is installed in a default region
• 2nd Stage: The MediaStore and SNS are installed.

The MediaStore and SNS are installed in each additional region which we need supported. The idea behind this is that if a workflow is created in a region different from the Default one and a channel is created with it, in order for the alerts to be intercepted an SNS is needed in the corresponding region, because MediaLive cannot send notifications cross region(This could no longer be the case depending on improvements and updates from the AWS side). For each region there is a flag showing if the region is the default one or not.

# MANAGED INPUTS:

Inputs are separated in two types:

• Managed
• Unmanaged

Both types are functioning the same way with one key difference. Unmanaged inputs are created and deleted in regards to channel creation and deletion while Managed Inputs can be created prior to channel creation and are not bound to channel creation and deletion. As a consequence of this the Managed inputs are keeping their IP addresses even after the channel has been stopped, while undamaged inputs receive a new IP Address with each channel start. Managed inputs inputs offer the advantage of having a static IP address, however it must be noted that the input is generating a running cost even when not in use.

Inputs are also separated in two other groups:

• VIRTUAL_INPUT
• CONNECTED_DEVICE

At the moment as CONNECTED_DEVICE is implemented only the Amazon Link device. Logical restriction is that from a single Amazon Link device only one Managed Input can be created. Trying to create a second Managed Input with the same device will result in an error. Each Amazon LInk device has two types of information for its state: Information for the Internet Connectivity State of whether the device settings are synchronized with the device itself When the type is VIRTUAL_INPUT defining for the input is the protocol. Supported protocols could be roughly separated in two general groups: PUSH and PULL. Each Managed Input has its own status which could be: LOCKED: MediaLive channel is in status: CREATE_FAILED, RECOVERING, DELETED, UPDATING, UPDATE_FAILED. These are internal AWS statuses for a channel or a so-called “temporary” conditions or such that cannot be recovered. DETACHED: The input can be attached to a workflow but no channel is created with it. ATTACHED: A channel which is created by a workflow that’s using the input is IDLE - i.e. created as a resource but not yet started.(Channel is with status IDLE) ACTIVE: A channel started from a workflow which uses the input is active i.e. channel status is: CREATING, STARTING, STOPPING, DELETING, RUNNING.

PULL protocols can be unprotected or protected with a username and password. PUSH protocols can have a list of CIDR blocks, which restrict who can push to them. When the protocol is ZIXI_PUSH, RIST, RTP_FEC or RTP, but only in a region different than the default region, only one CIDR block can be set. This is done in the same manner as when setting it for the default region’s PUSH inputs, however there can be only one element being set. In the information for each Managed Input there is a list with all Workflows, which are configured to use the Managed Input, but haven’t been started yet. After a channel has been started from a given workflow and then stopped or has encountered an error during starting/stopping the corresponding workflow is removed from the list. Choosing a region when creating a Managed input is not mandatory, however if the parameter is not passed in the request, the default region is used. While listing connected devices, if no managedInputId is set this means that there is no Managed Input created with the corresponding Amazon Link device.

Deletion of a managed input leads to deleting the resource associated with it, which means that the IP Address that has been attached to the managed input could NOT be the same next time a managed input is created with the same settings. A Managed Input can be edited only when its status is different from ATTACHED and DETACHED. When listing a detailed configuration for a Managed Input, if the input is of type CONNECTED_DEVICE, all of the Amazon Link devices’ settings are displayed.

# BLUEPRINTS / WORKFLOWS / CHANNELS

The Blueprint is a template with settings of a channel tested from the iOiO team. Blueprints are used as a foundation for creating a Workflow. A Channel is started only from a Workflow. A Workflow is a modified or unmodified instance of a Blueprint. A single Blueprint can be used for a number for Workflows. A single Blueprint consists of two portions: A list of inputs and settings for the future channel (encoding settings and output groups).

The list of inputs could contain two types of inputs:

• Managed
• Unmanaged

Settings for creating Unmanaged Input correspond absolutely to those for a Managed Input. While the settings in the channel key are one to one with the following AWS object:

• https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/medialive/model/CreateChannelRequest.html

• createRawArchive: indicates whether or not an archive should be created of the stream. Archives are managed by ioio, are recorded in MediaStore bucket and can be downloaded via download link, which can be obtained from GET /channels/{workflowId}

• adServers: For each destination (defined in the key settings.channel.destinations) there could be an adserverid passed on. Currently Dynamic Ad Insertions are supported for HLS only. Ad servers are created via the Broker service.

From one Workflow only one Channel can be started regardless if it’s successful or not. A second try for starting a channel that has already been started will result in duplication of the Workflow and starting a channel from the duplicated Workflow. Trying to start a channel from a Workflow that has been started already that did not manage to start successfully or an error has been received while starting will result in an error. Operation for stopping a channel is idempotent.

When a channel is starting there are alarms if errors occur. These can be observed via the dedicated API endpoint. It gives the possibility to see only the active alarms or a history of all alarms throughout the channel’s run.

A separate endpoint allows the observation of graphics which are related to the channel, these are:

• Network In
• Network Out
• Dropped Frames
• Active Alerts
• Input video frame rate
• Fill milliseconds
• UDP input loss
• SVQ Time

When attached to the channel are more than one input the functionality Input Switching can be used. Scheduling an ad break occurs 15 to 20 seconds after it has been scheduled. This is an AWS feature which currently cannot be overcome(will be reduced in future updates). In order for an Ad to be played, the corresponding destination needs to be “decorated”(to be described in the adServers array) with an Ad Server. Currently there is no way to tell which output is active with channels with multiple outputs.

Workflows can be filtered by the following criteria: One or more tags( Logical AND is being used when two or more tags are used; tag name is case insensitive) Workflow Status: Logical OR is used when two or more statuses are used. Date: sorting can be Ascending or Descending, Default sorting is Descending.

Another feature for workflows is a Scheduled start. When creating a workflow, the three fields can be used for a scheduled start and end: startDateTime: Time for when a channel with the workflow to be started. stopDateTime: Time for when the channel to be stopped. startDateTimeShiftMinutes: How many minutes before the given start time the channel to be started.