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

Entities 

ChannelResource

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

{
  "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. 

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

You can store any string type data under value field, fore example JSON encoded string, just not forget to escape it before passing API.

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

Images 

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

"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"
  }
]

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. 

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

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.

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.

Create channel with required values

example request

list default values

Create channel with all fulfilled values

example request

Multiple descriptions, names, channel numbers, domains

Multiple images

Update channel

Delete channel

How to implement channel operators behaviour

Migration guide

Known issues and limitations

Postman collection