Introduction

This section describes BSS communication with AminoTV Channels v4 API.

Authentication and authorisation

All BSS endpoints support API key authorization. The header named 'Authorization' with content "Apikey PUT_YOUR_KEY_HERE" must be passed with request.

In addition to API key authorization some clients can have IP white listing feature enabled, which will allow access only from exact IP's.

Both API key and IP addresses allowed list are customer specific data and you should contact support person to obtain those.

Endpoints overview

Endpoint	HTTP method	Purpose
/api/channel/management/v4/channels	GET	Get an index of channels.
/api/channel/management/v4/channels	POST	Create new channel
/api/channel/management/v4/channels/{channel_id}	GET	Get channel specified by id
/api/channel/management/v4/channels/{channel_id}	PATCH	Update channel specified by id
/api/channel/management/v4/channels/{channel_id}	DELETE	Delete channel specified by id and all related data

Entities

ChannelResource

Up-to-date resource schema could be found on API documentation page Management Channel API v4 under schemas section.

Code Block

language	yml
theme	Midnight
title	ChannelResource example
collapse	true

{
  "data": [
    {
      "id": "42",
      "type": "Channel",
      "attributes": {
        "name": [
          {
            "lang": "eng",
            "value": "English string"
          }
        ],
        "description": [
          {
            "lang": "eng",
            "value": "English string"
          }
        ],
        "images": [
          {
            "image_type": "Thumbnail",
            "alternate_access_description": "Bruce Willis shooting a big gun at some bad guys, pew pew pew",
            "width_pixels": 320,
            "height_pixels": 200,
            "iso_639-2_lang": "fin",
            "url": "https://www.demo.com/assets/img/thumbnails/movies/diehard.png"
          }
        ],
        "channel_number": {
          "default": 1
        },
        "media_type": "video",
        "enabled_services": [
          {
            "type": "Live",
            "startover": false,
            "pause": false,
            "trickplay": false,
            "restrictions": {
              "out_of_home": false
            }
          },
          {
            "type": "Catchup",
            "boundary_offset": 360,
            "trickplay": false,
            "restrictions": {
              "out_of_home": true
            }
          },
          {
            "type": "nPVR",
            "retention_time": 30,
            "watch_ongoing": false,
            "boundary_offset": 360,
            "trickplay": false,
            "restrictions": {
              "out_of_home": true
            }
          }
        ],
        "restrictions": {
          "geoblocking": true
        },
        "channel_domains": [],
        "visibility": {
          "start": 1605090698,
          "end": 1605095698
        },
        "dvb_info": [
          {
            "type": "C",
            "onid": 123,
            "tsid": 123,
            "sid": 4324,
            "quality": "SD"
          }
        ],
        "metadata_provider_information": [
          {
            "provider": "ERICSSON",
            "external_id": "724693092"
          }
        ]
      }
    }
  ]
}

Name and description

Name and description attributes can contain multiple values for each need language, we do not validate the values of those, only the language key which should be ISO 639-2 three letter code.

Code Block

theme	Midnight
title	Multiple names attribute

"name": [
  {
    "lang": "eng",
    "value": "English string"
  },
  {
    "lang": "dut",
    "value": "Dutch string"
  }
]

You can store any string type data under value field, fore example . If you need to store multiple values, you can, for example, use a JSON encoded string, just not forget . Just make sure to escape it before passing APIit to the API.

Code Block

theme	Midnight
title	Multiple names attribute

"name": [
  {
    "lang": "eng",
    "value": "{\"option1\": \"value1\",\"option2\": \"value2\",\"option3\": \"value3\"}"
  },
  {
    "lang": "dut",
    "value": "{\"option1\": \"value1\",\"option2\": \"value2\",\"option3\": \"value3\"}"
  }
]

Warning
It is expected that client will handle data parsing, specifically if some machine-readable value is stored.

Images

Images can store an array of objects, the image_type attribute could be used to identify image on client side.

Code Block

theme	Midnight
title	Multiple images
collapse	true

"images": [
  {
    "image_type": "Thumbnail",
    "alternate_access_description": "Bruce Willis shooting a big gun at some bad guys, pew pew pew",
    "width_pixels": 320,
    "height_pixels": 200,
    "iso_639-2_lang": "fin",
    "url": "https://www.demo.com/assets/img/thumbnails/movies/diehard.png"
  },
  {
    "image_type": "Thumbnail small",
    "alternate_access_description": "Bruce Willis shooting a big gun at some bad guys, pew pew pew",
    "width_pixels": 50,
    "height_pixels": 50,
    "iso_639-2_lang": "fin",
    "url": "https://www.demo.com/assets/img/thumbnails/movies/diehard_small.png"
  }
  {
    "image_type": "Thumbnail_option1",
    "alternate_access_description": "Bruce Willis shooting a big gun at some bad guys, pew pew pew",
    "width_pixels": 320,
    "height_pixels": 200,
    "iso_639-2_lang": "fin",
    "url": "https://www.demo.com/assets/img/thumbnails/movies/diehard_option1.png"
  }
]

Warning
It is up to client the customer to decide which naming will be used and where to store images.

Domains

The channel_domains works same as well-known tagging. In that case tag is called domain. There client could enter multiple tags mark channel to belong to some domain.

For example to mark channel as adult client can add "adult" domain and mark it as "testing" for own purposes. Then rely on that in client when fetching data for users.

Code Block

theme	Midnight
title	Multiple channel domains

"channel_domains": [
	"adult",
	"testing"
]

Warning
It is up to client to decide which channel domains will be used and set for channels and to sort those out for users.

Services

For details on what services are see Services section of Client Channel v4 APIs.

Management channels services has few more attributes which are not visible to user API and are implemented on API side.

"restrictions" attribute present in all enabled services , now it supports only "out_of_home" attribute which implements Out of home restrictions feature.

The "nPVR" service has additional "retention_time" attribute which defines for how long user recorder programme will be stored.

Warning
Unlike other services attributes those are implemented on backend and will affect application behaviour.

Use cases

Fetch channels

Get all channels

By calling Get an index of channels endpoint client could get paginated list of all existing channels. The default pagination limit is 100 items per page.

Get one channel

By calling Get channel endpoint client could obtain concrete channel data.

Create channel

By calling Create channel endpoint client could create new channel.

Code Block

theme	Midnight
title	Create channel with only required values
collapse	true

POST http://apidomain.xyz/api/channel/management/v4/channels
{
	'data' => {
        'type' => "Channel",
        'attributes' => {
            'name' => [
                [
                    'lang'  => "eng",
                    'value' => "test",
                ],
            ],
            'media_type' => "video"
        }
    }
}
RESPONSE 201 Created
{
  "data": {
    "type": "Channel",
    "id": "1",
    "attributes": {
      "name": [
        {
          "lang": "eng",
          "value": "test"
        }
      ],
      "description": [],
      "images": [],
      "channel_number": {
        "default": 0
      },
      "media_type": "video",
      "enabled_services": [],
      "restrictions": {
        "geoblocking": true
      },
      "channel_domains": [],
      "visibility": {
        "start": null,
        "end": null
      },
      "dvb_info": [],
      "metadata_provider_information": [
        {
          "provider": null,
          "external_id": null
        }
      ]
    }
  }
}

Code Block

theme	Midnight
title	Create channel with all values
collapse	true

POST http://apidomain.xyz/api/channel/management/v4/channels
{
  "data": {
    "type": "Channel",
    "attributes": {
      "name": [
        {
          "lang": "eng",
          "value": "TestChannel"
        }
      ],
      "description": [
        {
          "lang": "fin",
          "value": "TestChannelDesc"
        }
      ],
      "images": [
        {
          "image_type": "Thumbnail",
          "alternate_access_description": "Bruce Willis shooting a big gun at some bad guys, pew pew pew",
          "width_pixels": 320,
          "height_pixels": 200,
          "iso_639-2_lang": "fin",
          "url": "https://config.logo.24i.com/"
        }
      ],
      "channel_number": {
        "default": 123
      },
      "media_type": "video",
      "enabled_services": [
        {
          "type": "live",
          "startover": false,
          "pause": false,
          "trickplay": false,
          "restrictions": {
            "out_of_home": false
          }
        },
        {
          "type": "catchup",
          "trickplay": false,
          "boundary_offset": 0,
          "restrictions": {
            "out_of_home": false
          }
        },
        {
          "type": "npvr",
          "watch_ongoing": false,
          "trickplay": false,
          "boundary_offset": 360,
          "retention_time": 0,
          "restrictions": {
            "out_of_home": false
          }
        }
      ],
      "restrictions": {
        "geoblocking": false
      },
      "channel_domains": [
        "foo",
        "bar"
      ],
      "visibility": {
        "start": 1619010901,
        "end": 1619010901
      },
      "dvb_info": [
        {
          "type": "T",
          "onid": 11,
          "tsid": 22,
          "sid": 33,
          "quality": "HD"
        }
      ],
      "metadata_provider_information": [
        {
          "provider": "GRACENOTE",
          "external_id": "211176"
        }
      ]
    }
  }
}
RESPONSE 201 Created
{
  "data": {
    "type": "Channel",
    "id": "1",
    "attributes": {
      "name": [
        {
          "lang": "eng",
          "value": "TestChannel"
        }
      ],
      "description": [
        {
          "lang": "fin",
          "value": "TestChannelDesc"
        }
      ],
      "images": [
        {
          "image_type": "Thumbnail",
          "alternate_access_description": "Bruce Willis shooting a big gun at some bad guys, pew pew pew",
          "width_pixels": 320,
          "height_pixels": 200,
          "iso_639-2_lang": "fin",
          "url": "https://config.logo.24i.com/"
        }
      ],
      "channel_number": {
        "default": 123
      },
      "media_type": "video",
      "enabled_services": [
        {
          "type": "live",
          "startover": false,
          "pause": false,
          "trickplay": false,
          "restrictions": {
            "out_of_home": false
          }
        },
        {
          "type": "catchup",
          "trickplay": false,
          "boundary_offset": 0,
          "restrictions": {
            "out_of_home": false
          }
        },
        {
          "type": "npvr",
          "watch_ongoing": false,
          "trickplay": false,
          "boundary_offset": 360,
          "retention_time": 0,
          "restrictions": {
            "out_of_home": false
          }
        }
      ],
      "restrictions": {
        "geoblocking": false
      },
      "channel_domains": [
        "foo",
        "bar"
      ],
      "visibility": {
        "start": 1619010901,
        "end": 1619010901
      },
      "dvb_info": [
        {
          "type": "T",
          "onid": 11,
          "tsid": 22,
          "sid": 33,
          "quality": "HD"
        }
      ],
      "metadata_provider_information": [
        {
          "provider": "GRACENOTE",
          "external_id": "211176"
        }
      ]
    }
  }
}

Update channel

Use update channel endpoint.

Warning
Array typed attributes does not support partial updates. To update those attributes you must send full new array of data.

Delete channel

Use delete channel endpoint.

Migration guide

How to implement adult channels

Use update channel endpoint and add "adult" domain to channel. Filter it on client side.

How to implement local channels

Use update channel endpoint and add "local" domain to channel. Filter

Code Block

theme	Midnight
title	Enable catchup for channel
collapse	true

# First get channel data through GET endpoint
GET http://apidomain.xyz/api/channel/management/v4/channels/:channelId
RESPONSE 200
{
  "data": {
    "type": "Channel",
    "id": ":channelId",
    "attributes": {
      "name": [
        {
          "lang": "eng",
          "value": "TestChannel"
        }
      ],
      "description": [
        {
          "lang": "fin",
          "value": "TestChannelDesc"
        }
      ],
      "images": [
        {
          "image_type": "Thumbnail",
          "alternate_access_description": "Bruce Willis shooting a big gun at some bad guys, pew pew pew",
          "width_pixels": 320,
          "height_pixels": 200,
          "iso_639-2_lang": "fin",
          "url": "https://config.logo.24i.com/"
        }
      ],
      "channel_number": {
        "default": 123
      },
      "media_type": "video",
      "enabled_services": [
        {
          "type": "live",
          "startover": false,
          "pause": false,
          "trickplay": false,
          "restrictions": {
            "out_of_home": false
          }
        },
        {
          "type": "npvr",
          "watch_ongoing": false,
          "trickplay": false,
          "boundary_offset": 360,
          "retention_time": 0,
          "restrictions": {
            "out_of_home": false
          }
        }
      ],
      "restrictions": {
        "geoblocking": false
      },
      "channel_domains": [
        "foo",
        "bar"
      ],
      "visibility": {
        "start": 1619010901,
        "end": 1619010901
      },
      "dvb_info": [
        {
          "type": "T",
          "onid": 11,
          "tsid": 22,
          "sid": 33,
          "quality": "HD"
        }
      ],
      "metadata_provider_information": [
        {
          "provider": "GRACENOTE",
          "external_id": "211176"
        }
      ]
    }
  }
}


#Prepare request body to enable catchup service and issue update channel PATCH request, add needed fields according to API spec
#Not provided values will be set t defaults 
PATCH http://apidomain.xyz/api/channel/management/v4/channels/:channelId
{
    "data": {
        "type": "Channel",
        "id": ":channelId",
        "attributes": {
            "enabled_services": [
                {
                    "type": "live",
                    "startover": true,
                    "pause": false,
                    "trickplay": true,
                    "restrictions": {
                        "out_of_home": false
                    }
                },
                {
                    "type": "catchup",
                    "boundary_offset": 604800
                },
                {
                    "type": "npvr",
                    "watch_ongoing": false,
                    "trickplay": true,
                    "boundary_offset": 0,
                    "retention_time": 365,
                    "restrictions": {
                        "out_of_home": false
                    }
                }
            ]
        }
    }
}
RESPONSE 200
{
  "data": {
    "type": "Channel",
    "id": ":channelId",
    "attributes": {
      "name": [
        {
          "lang": "eng",
          "value": "TestChannel"
        }
      ],
      "description": [
        {
          "lang": "fin",
          "value": "TestChannelDesc"
        }
      ],
      "images": [
        {
          "image_type": "Thumbnail",
          "alternate_access_description": "Bruce Willis shooting a big gun at some bad guys, pew pew pew",
          "width_pixels": 320,
          "height_pixels": 200,
          "iso_639-2_lang": "fin",
          "url": "https://config.logo.24i.com/"
        }
      ],
      "channel_number": {
        "default": 123
      },
      "media_type": "video",
      "enabled_services": [
        {
          "type": "live",
          "startover": false,
          "pause": false,
          "trickplay": false,
          "restrictions": {
            "out_of_home": false
          }
        },
		{
          "type": "catchup",
          "trickplay": true,
          "boundary_offset": 604800,
          "restrictions": {
            "out_of_home": false
          }
        },
        {
          "type": "npvr",
          "watch_ongoing": false,
          "trickplay": false,
          "boundary_offset": 360,
          "retention_time": 0,
          "restrictions": {
            "out_of_home": false
          }
        }
      ],
      "restrictions": {
        "geoblocking": false
      },
      "channel_domains": [
        "foo",
        "bar"
      ],
      "visibility": {
        "start": 1619010901,
        "end": 1619010901
      },
      "dvb_info": [
        {
          "type": "T",
          "onid": 11,
          "tsid": 22,
          "sid": 33,
          "quality": "HD"
        }
      ],
      "metadata_provider_information": [
        {
          "provider": "GRACENOTE",
          "external_id": "211176"
        }
      ]
    }
  }
}

Delete channel

Use delete channel endpoint.

Migration guide

How to implement adult channels

Use update channel endpoint and add "adult" domain to channel. Filter it on client side.

How to implement local channels

Use update channel endpoint and add "local" domain to channel. Filter it on client side.

How to implement operator channels behaviour

Operator channels feature is not a part of backend anymore, we provide means to support that feature on client side.

To have 2 operators for channels create or update channel with similar request (only sufficient attributes present in request).

Code Block

theme	Midnight
title	Operator channels example
collapse	true

POST http://apidomain.xyz/api/channel/management/v4/channels
{
  "data": {
    "type": "Channel",
    "attributes": {
      "name": [
        {
          "lang": "eng",
          "value": "{\"operator1\": \"value1\",\"operator2\": \"value2\"}"
        }
      ],
      "description": [
        {
          "lang": "eng",
          "value": "{\"operator1\": \"value1\",\"operator2\": \"value2\"}"
        }
      ],
      "images": [
        {
          "image_type": "Thumbnail_operator1",
          "alternate_access_description": "Bruce Willis shooting a big gun at some bad guys, pew pew pew",
          "width_pixels": 320,
          "height_pixels": 200,
          "iso_639-2_lang": "fin",
          "url": "https://config.logo.24i.com/"
        },
        {
          "image_type": "Thumbnail_operator2",
          "alternate_access_description": "Bruce Willis shooting a big gun at some bad guys, pew pew pew",
          "width_pixels": 320,
          "height_pixels": 200,
          "iso_639-2_lang": "fin",
          "url": "https://config.logo.24i.com/"
        }
      ],
      "channel_number": {
        "operator1": 7,
        "operator2": 42
      },
     "media_type": "video"
    }
  }
}

Given:

operator1, operator2 - are unique operators identifiers
image_type attribute is build with rule ImageType_OperatorId

After that when fetching channel data in client applications sort out data for needed operator. Flow could look like:

Fetch channels data
Decide which operator is used
Decode name and description and use appropriate value
Find image by image_type
Find channel number by operator id
Use in application

Known issues and limitations

This API does not support old fashioned operator channels feature. Instead clients are expected to implement it on their side.

Postman collection

View file

name	ChannelManagementV4.gz
height	250

Table of Contents

Version	Old Version 25	New Version Current
Changes made by	Former user	Former user
Saved on	Apr 22, 2021	Sept 07, 2021

Versions Compared

Key

Introduction

Authentication and authorisation

Endpoints overview

Entities

ChannelResource

Name and description

Images

Domains

Use cases

Fetch channels

Get all channels

Get one channel

Create channel

Update channel

Delete channel

Migration guide

How to implement adult channels

How to implement local channels

Delete channel

Migration guide

How to implement adult channels

How to implement local channels

How to implement operator channels behaviour

Known issues and limitations

Postman collection

Table of Contents

Page Comparison

Versions Compared

Key

Introduction

Authentication and authorisation

Endpoints overview

Entities

ChannelResource

Name and description

Images

Domains

Use cases

Fetch channels

Get all channels

Get one channel

Create channel

Update channel

Delete channel

Migration guide

How to implement adult channels

How to implement local channels

Delete channel

Migration guide

How to implement adult channels

How to implement local channels

How to implement operator channels behaviour

Known issues and limitations

Postman collection

Table of Contents