Page Comparison

Introduction

This section describes BSS communication with AminoTV License v4 API. Products and user licenses are manageable through License Management API.

The license management API consist of two parts: licenses management and products management. No caching is used with those endpoints.

Entities

The resource descriptions could be found on API documentation page Management Licenses

Introduction

This section describes BSS communication with AminoTV License v4 API. Products and user licenses are manageable through License Management API.

The license management API consist of two parts: licenses management and products management. No caching is used with those endpoints.

Entities

The resource descriptions could be found on API documentation page Management Licenses v4

License resource

Typical license resource may look like the one below.

Code Block

language	text
theme	Midnight
title	License resource example

{
  "id": "42",
  "type": "License",
  "attributes": {
    "status": "ACTIVE",
    "start_date": 1523268666,
    "stop_date": 1523268698,
    "order_id": "1adc0dbe-3c65-4248-896c-78c049e276c8",
    "renew_record": {
      "recurring": true,
      "expiry_date": 1523268698
    },
    "purchase_record": {
      "price_currency_amount": 1223,
      "price_currency_iso4217": "EUR",
      "purchase_timestamp": 1526648593,
      "payment_method": "credit card"
    }
  },
  "relationships": {
    "user": {
      "data": {
        "id": "41",
        "type": "User"
      }
    },
    "product": {
      "data": {
        "id": "41",
        "type": "Product"
      }
    }
  }
}

Product resource

Product resource may looks like one below.

Code Block

language	text
theme	Midnight
title	Product resource example

{
  "id": "41",
  "type": "Product",
  "attributes": {
    "title": "Sport channels meagpack",
    "description": "Complete collection fo all sports channels",
    "is_premium": true,
    "price_record": {
      "amount": 98,
      "currency": "EUR"
    },
    "license_duration": 518400,
    "type": "CATCHUP",
    "auto_grant_on_signup": false,
    "auto_renew": false,
    "is_user_visible": true,
    "is_buyable": true
  },
  "relationships": {
    "live": {
      "data": [
        {
          "id": "42",
          "type": "Channel"
        }
      ]
    },
    "catchup": {
      "data": [
        {
          "id": "42",
          "type": "Channel"
        }
      ]
    },
    "npvr": {
      "data": [
        {
          "id": "42",
          "type": "Channel"
        }
      ]
    },
    "startover": {
      "data": [
        {
          "id": "42",
          "type": "Channel"
        }
      ]
    }
  }
}

Info
Please note that only products with both is_user_visible and is_buyable attributes set will be available for users to purchase

Authorization

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

Licenses management

Fetch licenses

Endpoints overview

Id	Endpoint	HTTP method	Purpose
GetLicenses	/api/license/management/v4/licenses	GET	Fetch list of licenses with filters
GetLicenseById	/api/license/management/v4/licenses/{license_id}	GET	Get license specified by id
GetLicensesByUser	/api/license/management/v4/users/{user_id}/licenses	GET	Get all user licenses

BSS can get list of licenses with filters, all user licenses and single license. GetLicenses and GetLicenseById calls return an array of licenses with all relationships and also contain included section with all products associated to fetched licenses. GetLicenses by default has a limit of 100 results per page and GetLicensesByUser will always return all results. GetLicenseById will return single license resource and associated product in included section.

GetLicenseById allows filtering by several parameters:

filter[user_id] - by user

filter[with_auto_renew] - by renew_record.recurring value

filter[status] - by status value, list of statuses described in resource

filter[payment_method] - by payment_method value, it is possible to specify 'none' to get licenses which has no payment method set (null in DB).

filter[purchase_later_than] - return only licenses which purchase_date is later then specified

filter[active_from] - return only licenses which start_date is later than specified

filter[active_until] - return only licenses which stop_date is earlier than specified

page[number] - if multiple pages result returned then client can iterate through all results specifying page parameter

GetLicenses endpoint supports filtering, pleases check API documentation on filtering parameters details.

Use cases

Get all licenses that are added to a user account

Code Block

theme	Midnight

http://apidomain.xyz/api/license/management/v4/users/42}/licenses

will return all licenses in one request or

Code Block

theme	Midnight

http://apidomain.xyz/api/license/management/v4/licenses?filter[user_id]=42

which would return paginated results with limit of 100 per page.

Get only active licenses that are purchased by user during this last month

Users license API always specifies 'billing' as payment method. Please note that purchase_later_then value here is just example.

Code Block

theme	Midnight

http://apidomain.xyz/api/license/management/v4/licenses?filter[user_id]=42&filter[status]=ACTIVE&filter[payment_method]=billing&filter[purchase_later_than]=1591715002

Get second page of active licenses that has no set payment method

Code Block

theme	Midnight

http://apidomain.xyz/api/license/management/v4/licenses?filter[status]=ACTIVE&filter[payment_method]=none&page[number]=

BSS can get the products that are added to a user account

This operation can be done with same requests as above. Each response will have included section with products associated with granted licenses.

Create licenses

Endpoints overview

Id	Endpoint	HTTP method	Purpose
CreateLicense	/api/license/management/v4/licenses	POST	Grant license on specified product to user

The create license endpoint requires an Idempotency-Key parameter to be present in the headers. The client should generate some adequately unique random value for this header, which should be sent along with the purchasing request. The purpose of this header is to prevent accidentally making multiple API calls to purchase the same product due to a connection error. If the request is made multiple times with the same idempotency key, then the API exhibits idempotent behavior, meaning it will return the same response as in the previous call without processing another purchase request. It is there for safe to call the API multiple times if the response was lost, as long as the same idempotency key is used in subsequent requests.

If any of non-mandatory license parameters is omitted then the value will be taken from associated product.

Use cases

BSS can add product to a user account with a single call

Code Block

theme	Midnight
title	Add product to a user
collapse	true

POST http://apidomain.xyz/api/license/management/v4/licenses
{
  "data": {
    "type": "License",
    "attributes": {
      "start_date": 1523268666,
      "stop_date": 1523268698,
      "renew_record": {
        "recurring": true
      },
      "purchase_record": {
        "price_currency_amount": 1223,
        "price_currency_iso4217": "EUR",
        "purchase_timestamp": 1526648593,
        "payment_method": "credit card"
      }
    },
    "relationships": {
      "user": {
        "data": {
          "id": "41",
          "type": "User"
        }
      },
      "product": {
        "data": {
          "id": "41",
          "type": "Product"
        }
      }
    }
  }
}
RESPONSE 201 Created
{
  "data": {
    "id": "42",
    "type": "License",
    "attributes": {
      "status": "ACTIVE",
      "start_date": 1523268666,
      "stop_date": 1523268698,
      "order_id": "1adc0dbe-3c65-4248-896c-78c049e276c8",
      "renew_record": {
        "recurring": true,
        "expiry_date": 1523268698
      },
      "purchase_record": {
        "price_currency_amount": 1223,
        "price_currency_iso4217": "EUR",
        "purchase_timestamp": 1526648593,
        "payment_method": "credit card"
      }
    },
    "relationships": {
      "user": {
        "data": {
          "id": "41",
          "type": "User"
        }
      },
      "product": {
        "data": {
          "id": "41",
          "type": "Product"
        }
      }
    }
  }
}

Delete licenses

Endpoints overview

Id	Endpoint	HTTP method	Purpose
DeleteLicenseById	/api/license/management/v4/licenses/{license_id}	DELETE	Delete license by id

Use cases

BSS can remove product from a user account with a single call

Code Block

theme	Midnight
title	Remove product from a user

POST http://apidomain.xyz/api/license/management/v4/licenses/42
RESPONSE 204 Deleted

Batch operations

Endpoints overview

Id	Endpoint	HTTP method	Purpose
BatchCreateLicenses	/api/license/management/v4/licenses/batch_create	POST	Create multiple licenses
BatchDeleteLicenses	/api/license/management/v4/licenses/batch_delete	POST	Delete multiple licenses

Batch operations are limited to process up to 1000 items per request. Those endpoints are not designed to be high performant thus keep in mind that with big amount of input items it would take some time to receive a response. Also operation will fail on first occurred error and return error message for specified item.

BatchCreateLicenses request requires same Idempotency-Key parameter to be present in header same as described for CreateLicense endpoint. The response will contain included section with details on associated products.

Use cases

BSS can add multiple products to a user account with a single call

Code Block

theme	Midnight
title	Add multiple products to multiple users
collapse	true

POST http://apidomain.xyz/api/license/management/v4/licenses/batch_create
{
  "data": [
    {
      "type": "License",
      "attributes": {
        "start_date": 1523268666,
        "stop_date": 1523268698,
        "renew_record": {
          "recurring": true
        },
        "purchase_record": {
          "price_currency_amount": 1223,
          "price_currency_iso4217": "EUR",
          "purchase_timestamp": 1526648593,
          "payment_method": "credit card"
        }
      },
      "relationships": {
        "user": {
          "data": {
            "id": "42",
            "type": "User"
          }
        },
        "product": {
          "data": {
            "id": "1",
            "type": "Product"
          }
        }
      }
    },
    {
      "type": "License",
      "attributes": {
        "start_date": 1523268999,
        "stop_date": 1523268876,
        "renew_record": {
          "recurring": true
        },
        "purchase_record": {
          "price_currency_amount": 342,
          "price_currency_iso4217": "EUR",
          "purchase_timestamp": 1523268999,
          "payment_method": "bank transfer"
        }
      },
      "relationships": {
        "user": {
          "data": {
            "id": "42",
            "type": "User"
          }
        },
        "product": {
          "data": {
            "id": "2",
            "type": "Product"
          }
        }
      }
    }
  ]
}

RESPONSE 201 Created
{
  "data": [
    {
      "id": "13",
      "type": "License",
      "attributes": {
        "status": "ACTIVE",
        "start_date": 1523268666,
        "stop_date": 1523268698,
        "order_id": "1adc0dbe-3c65-4248-896c-78c049e276c8",
        "renew_record": {
          "recurring": true,
          "expiry_date": 1523268698
        },
        "purchase_record": {
          "price_currency_amount": 1223,
          "price_currency_iso4217": "EUR",
          "purchase_timestamp": 1526648593,
          "payment_method": "credit card"
        }
      },
      "relationships": {
        "user": {
          "data": {
            "id": "42",
            "type": "User"
          }
        },
        "product": {
          "data": {
            "id": "1",
            "type": "Product"
          }
        }
      }
    },
	{
      "id": "13",
      "type": "License",
      "attributes": {
        "status": "ACTIVE",
        "start_date": 1523268999,
        "stop_date": 1523268876,
        "order_id": "1adc0dbe-3c65-4248-896c-78c049e276c8",
        "renew_record": {
          "recurring": true,
          "expiry_date": 1523268698
        },
        "purchase_record": {
          "price_currency_amount": 342,
          "price_currency_iso4217": "EUR",
          "purchase_timestamp": 1523268999,
          "payment_method": "bank transfer"
        }
      },
      "relationships": {
        "user": {
          "data": {
            "id": "42",
            "type": "User"
          }
        },
        "product": {
          "data": {
            "id": "2",
            "type": "Product"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "1",
      "type": "Product",
      "attributes": {
        "title": "Sport channels meagpack",
        "description": "Complete collection fo all sports channels",
        "is_premium": true,
        "price_record": {
          "amount": 98,
          "currency": "EUR"
        },
        "license_duration": 518400,
        "type": "CATCHUP",
        "auto_grant_on_signup": false,
        "auto_renew": false,
        "is_user_visible": true,
        "is_buyable": true
      },
      "relationships": {
        "live": {
          "data": [
            {
              "id": "42",
              "type": "Channel"
            }
          ]
        },
        "catchup": {
          "data": [
            {
              "id": "42",
              "type": "Channel"
            }
          ]
        },
        "npvr": {
          "data": [
            {
              "id": "42",
              "type": "Channel"
            }
          ]
        },
        "startover": {
          "data": [
            {
              "id": "42",
              "type": "Channel"
            }
          ]
        }
      }
    },
	{
      "id": "2",
      "type": "Product",
      "attributes": {
        "title": "Discovery channels meagpack",
        "description": "Complete collection fo all Discovery channels",
        "is_premium": true,
        "price_record": {
          "amount": 98,
          "currency": "EUR"
        },
        "license_duration": 518400,
        "type": "CATCHUP",
        "auto_grant_on_signup": false,
        "auto_renew": false,
        "is_user_visible": true,
        "is_buyable": true
      },
      "relationships": {
        "live": {
          "data": [
            {
              "id": "1",
              "type": "Channel"
            }
          ]
        },
        "catchup": {
          "data": [
            {
              "id": "2",
              "type": "Channel"
            }
          ]
        },
        "npvr": {
          "data": [
            {
              "id": "3",
              "type": "Channel"
            }
          ]
        },
        "startover": {
          "data": [
            {
              "id": "4",
              "type": "Channel"
            }
          ]
        }
      }
    }
  ]
}

BSS can delete multiple products from a user account with a single call

Code Block

theme	Midnight
title	Remove multiple products
collapse	true

POST http://apidomain.xyz/api/license/management/v4/licenses/batch_delete
{
  "data": [
    {
      "id": "2",
      "type": "License"
    },
	{
      "id": "7",
      "type": "License"
    },
	{
      "id": "34",
      "type": "License"
    }
  ]
}
RESPONSE 204 Deleted

BSS can revoke all subscribed products from a user

Client can perform same call as for removing multiple products from multiple users but limited to one user licenses.

Migration from legacy

Products management

Fetch products

Id	Endpoint	HTTP method	Purpose
GetAllProducts	/api/license/management/v4/products	GET	Get all product
GetProductById	/api/license/management/v4/products/{product_id}	GET	Get product bu Id

Create products

Id	Endpoint	HTTP method	Purpose
CreateProduct	/api/license/management/v4/products	POST	Create new product

Update products

Id	Endpoint	HTTP method	Purpose
UpdateProduct	/api/license/management/v4/products/{product_id}	PATCH	Update product attributes

Delete products

Id	Endpoint	HTTP method	Purpose
DeleteProductById	/api/license/management/v4/products/{product_id}	DELETE	Delete product by id

Migration from legacy

DRM providers support

Irdeto

Hybris

What else?

Table of Contents

Version	Old Version 41	New Version 42
Changes made by	Former user	Former user
Saved on	Jun 10, 2020	Jun 10, 2020

Page Comparison

Versions Compared

Key

Introduction

Entities

Introduction

Entities

License resource

Authorization

Licenses management

Fetch licenses

Endpoints overview

Use cases

Get all licenses that are added to a user account

Get only active licenses that are purchased by user during this last month

Get second page of active licenses that has no set payment method

BSS can get the products that are added to a user account

Create licenses

Endpoints overview

Use cases

BSS can add product to a user account with a single call

Delete licenses

Endpoints overview

Use cases

BSS can remove product from a user account with a single call

Batch operations

Endpoints overview

Use cases

BSS can add multiple products to a user account with a single call

BSS can delete multiple products from a user account with a single call

BSS can revoke all subscribed products from a user

Migration from legacy

Products management

Fetch products

Create products

Update products

Delete products

Migration from legacy

DRM providers support

Irdeto

What else?