Introduction
User's access to services provided by the AminoTV API are handled by Licenses. In order to use a service, the user must first be issued a License to a Product granting access to the requested service.
Entities overview
See User License API specification.
| Entity | Purpose |
|---|---|
| Product | A Product represents a collection of services to which a user may be granted access. Products are defined by the service provider. |
| License | A License grants access for one user to the services granted by one Product. A user may have several licenses. Licenses can be purchased, revoked and expired. |
Purchasing
Endpoints overview
| Id | Endpoint | HTTP method | Purpose |
|---|---|---|---|
| PurchaseUserLicense | /api/license/v4/users/{user_id}/licenses | POST |
| Purchase user license. This implies some method of payment is provided. |
A user may purchase a License for themselves by calling the create license endpoint. In order to create a license, some method of payment must be provided. At the moment only one method of payment is supported: "billing". With this payment method, no further payment details are necessary, but the user is charged through the service provider's billing system.
...
Listing licenses and products
Endpoints overview
| Id | Endpoint | HTTP method | Purpose |
|---|---|---|---|
| GetUserLicenses | GET | Get user licenses | |
| GetAllProducts | GET | Get all products |
It is possible to show to the user existing licenses and filter them by status. Client can filter licenses on it's side by next attributes:
- status in [PROCESSING, CHECK_INVALID, ORDER_ERROR, ACTIVE, EXPIRED, SUSPENDED, SUSPENDEDADMIN]
- start_date - when the license was activated, in unix epoch timestamp
- end_date - when the license is going to be deactivated, in unix epoch timestamp
Every license object from returned list include product for which the license was issued
Client may obtain a list of products to combine with a list of licenses to show to the end-user.
Use cases
Let user select product and purchase it
With a call to 'Get all productsGetAllProducts' client can obtain a list of all visible and buyable (those products attributes could be changed through management license API) product objects which will look similar to
...
The 'type' attribute could be one of:
Value in API | Service description |
|---|---|
| CHANNEL | The product grants to user ability to watch associated channel |
| PVR | The product grants to user ability to record associated channel to their cloud storage account |
| CATCHUP | The product grants to user ability to watch programs that aired previously and are still within the defined catchup window for associated channel |
| STARTOVER | The product grants to user ability to restart a live program on associated channel from the beginning |
| CHANNEL_GROUP | The product is a collection of several channels with different services available for each channel, in other words a mix of all types above. |
The 'relationships' here are same as defined at Channel API. If the channel is listed in relationship section then this service for that channel is available.
Value in API | Service description |
|---|---|
| live | The user may watch this channel as a live stream |
| npvr | The user is allowed to record this channel to their cloud storage account |
| catchup | The user is permitted to watch programs that aired previously and are still within the defined catchup window (typically 2 weeks) |
| startover | The user is permitted to restart a live program from the beginning. |
Having this data should be enough to represent available products and what channels and services those provide to user.
After user selected product he needs it can be purchased with request to 'Issue a license to a userPurchaseUserLicense' endpoint.
Allow user to view his licenses
When client can requests 'Get user licensesGetUserLicenses' endpoint response received contains all of user licenses and also includes all associated products. From here licenses could be combined with it's associated products by id, filtered by status (for example to show only active) and represented to end-user, those which are close to expire could be spotted via stop_date and marked with some warning.
...