- Created by Former user , last modified on Jul 23, 2020
You are viewing an old version of this page. View the current version.
Compare with Current View Version History
« Previous Version 58 Next »
VMX integration is not supported within this API
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 resources descriptions could be found on API documentation page Management Licenses v4 under schemas section.
LicenseResource
Typical license resource may look like the one below.
{
"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"
}
}
}
}
ProductResource
Product resource may looks like one below.
{
"id": "41",
"type": "Product",
"attributes": {
"title": "Sport channels meagpack",
"description": "Complete collection fo all sports channels",
"price_record": {
"amount": 98,
"currency": "EUR"
},
"license_defaults": {
"duration": 518400,
"auto_renew": false,
},
"is_premium": true,
"auto_grant_on_signup": 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"
}
]
}
}
}
Please note that it is recommended to clients to show as available for end-users to purchase only products with both is_user_visible and is_buyable attributes set. See Listing licenses and products for more information on topic.
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. Pleases check API documentation on GetLicenseById filtering parameters details.
GetLicenseById will return single license resource and associated product in included section.
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 with included products or
http://apidomain.xyz/api/license/management/v4/licenses?filter[user_id]=42
which will return paginated results with limit of 100 per page without included products but with included users
http://apidomain.xyz/api/license/management/v4/licenses?filter[user_id]=42&include=product
will return paginated results with limit of 100 per page with included products
Get licenses which were 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[payment_method]=billing&filter[purchase_later_than]=1591715002
Will return return paginated results with limit of 100 per page without included products and
http://apidomain.xyz/api/license/management/v4/licenses?filter[user_id]=42&filter[payment_method]=billing&filter[purchase_later_than]=1591715002&included=product
will return paginated results with limit of 100 per page with included products
Get second page of licenses that has no set payment method
http://apidomain.xyz/api/license/management/v4/licenses?filter[payment_method]=none&page[number]=2
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 allow retrying requests that might fail due to e.g. a network error without risking purchasing the same product twice. 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
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
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
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",
"price_record": {
"amount": 98,
"currency": "EUR"
},
"license_defaults": {
"duration": 518400,
"auto_renew": false,
},
"is_premium": true,
"auto_grant_on_signup": 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_defaults": {
"duration": 518400,
"auto_renew": false,
},
"is_premium": true,
"auto_grant_on_signup": 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
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
POST `/api/management/user/<email>/product` endpoint is replaced with POST '/api/license/management/v4/licenses' endpoint and extended with POST '/api/license/management/v4/licenses/batch_create' endpoint for multiple entries.
DELETE '/api/management/user/<email>/product/<product_id>' endpoint is replaced with DELETE '/api/license/management/v4/licenses/{license_id}' endpoint and extended with POST '/api/license/management/v4/licenses/batch_delete' endpoint for multiple entries.
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
Postman collection
licenseV4Collection.tar.gz - the archive contains collection and environment configured to use postman mock service.
You need to import collection and environment into postman, create another postman mock server to use and set it in environment.
Under the collection there are two folders:
- API Spec - which contains all request just as they appear on the swaggerhub.
- UseCase - under this folder there are typical use cases with examples and some tests, only to check response codes, this folder could be also used to run in postman collection runner.
DRM providers support
Irdeto
Hybris
What else?
- No labels