Skip to end of banner
Go to start of banner

Management license

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Version History

« Previous Version 40 Next »

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

License resource

Typical license resource may look like the one below and it consists of 3 parts.

License resource 
{
  "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"
      }
    }
  }
}

Resource identification:

  • id - unique license resource identifier - auto generated value, this value is used when operating over license

  • type - resource type, must be 'License' 

Attributes:

  • status - current license status, could be one of [PROCESSING, CHECK_INVALID, ORDER_ERROR, ACTIVE, EXPIRED, SUSPENDED, SUSPENDEDADMIN]:
    • ACTIVE - this is the only status which allows end-user to watch the content license was created for, it is default status for newly created o licenses
    • SUSPENDED - license was suspended by client through BSS or by AminoTV support via CMS
    • SUSPENDEDADMIN - license was suspended by AminoTV script
    • EXPIRED - license life time expired, managed by AminoTV scripts
    • ORDER_ERROR, CHECK_INVALID, PROCESSING - are internal statuses for matching orders with external systems (Hybris SAP)
  • start_date - timestamp when the license should become active
  • stop_date - timestamp when the license will expire
  • order_id - field used to store order id, which is generated by internal scripts when purchasing/prolonging licenses with 3rd party services
  • renew_record.recurring - with setting this attribute client can specify should the license be auto renewable or not, if the attribute omitted then value from associated product used.
  • renew_record.expiry_date - expiration date of the licenses, if the renew_record.recurring attribute set to true then licenses renewal scripts will rely on this attribute to select licenses to process
  • purchase_record.price_currency_amount - price of the license in cents, if this is not provided the value from associated product will be used
  • purchase_record.price_currency_iso4217 - currency of the license price, if this is not provided the value from associated product will be used
  • purchase_record.purchase_timestamp - timestamp to set license purchase date, this could be useful when license created separately on client side and then added to system, if no value provided then current timestamp will be used
  • purchase_record.payment_method - the method license was payed with, as we do not support any billing system clients should manage payments processing by themselves and can just pass any convenient string here. Please note that for users license API payment method 'billing' will be used by default.

Relationships:

  • user - user identifier identifier and type 'User' to grant license

  • product - product identifier and type 'Product' to associate license with

Product resource

Product resource may looks like one below.

Product resource 
{
  "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"
        }
      ]
    }
  }
}

Resource identification:

  • id - unique product resource identifier - auto generated value, this value is used when operating over license

  • type - resource type, must be 'Product' 

Attributes:

  • title - required product title
  • description - optional product description
  • is_premium - optional, flag to identify product as premium, used by packages import scripts, false by default
  • price_record.amount - required product price in cents
  • price_record.currency - required product price currency
  • license_duration - required duration in seconds to use as default when issuing license n this product
  • type - type of package, could be one of:
  • CATCHUP - product contains only catchup items
  • CHANNEL - product contains able channel items
  • PVR - product contains only npvr items
  • STARTOVER - product contains only starter items
  • CHANNEL_GROUP - product contains mixed items
  • auto_grant_on_signup - defines should license on this product be issued for every new user created
  • auto_renew - defines should the license issued for that product be recurring or not
  • is_user_visible - defines should users see the product in the list of available
  • is_buyable - defines should users be able to purchase this product

Relationships:

  • live - list of channels which user can watch as a live stream
  • catchup - list of channels which programs that aired previously and are still within the defined catchup window (typically 2 weeks) a user is permitted to watch
  • npvr - list of channels which user can record to their cloud storage account
  • startover - list of channels which user is permitted to restart a live program from the beginning


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/licensesGETFetch list of licenses with filters
GetLicenseById/api/license/management/v4/licenses/{license_id}GETGet license specified by id
GetLicensesByUser/api/license/management/v4/users/{user_id}/licensesGETGet 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

Use cases

Get all licenses that are added to a user account
http://apidomain.xyz/api/license/management/v4/users/42}/licenses

will return all licenses in one request or

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.

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
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/licensesPOSTGrant 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
Add product to a user 
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}DELETEDelete license by id

Use cases

BSS can remove product from a user account with a single call
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_createPOSTCreate multiple licenses
BatchDeleteLicenses/api/license/management/v4/licenses/batch_deletePOSTDelete 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
Add multiple products to multiple users 
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
Remove multiple products 
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/productsGETGet all product
GetProductById/api/license/management/v4/products/{product_id}GETGet product bu Id

Create products

Id

Endpoint

HTTP method

Purpose

CreateProduct/api/license/management/v4/productsPOSTCreate new product

Update products

Id

Endpoint

HTTP method

Purpose

UpdateProduct/api/license/management/v4/products/{product_id} PATCHUpdate product attributes

Delete products

Id

Endpoint

HTTP method

Purpose

DeleteProductById/api/license/management/v4/products/{product_id} DELETEDelete product by id

Migration from legacy


DRM providers support

Irdeto

Hybris

What else?

  • No labels