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 /wiki/spaces/MAPI/pages/49676828See User License API
| 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
| Endpoint | HTTP method | Purpose |
|---|---|---|
| /api/license/v4//users/{user_id}/licenses | POST | Issue a license to a user. 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.
...
| Warning |
|---|
The purchasing API does not restrict the user from purchasing a License for a Product even if they already have a License for the given Product. If different idempotency keys are used for purchasing, then multiple Licenses will be purchased for the user. |
Billing
If the service provider supports billing as a payment method, then they are responsible for handling the billing of the customer separately. A list of all purchased licenses can be obtained through the management API, see License Management Endpoints#/Licenses/ GetLicenses. The order ID of a license uniquely identifies each purchase. This identifier should be used to make sure the user is not billed multiple times for the same purchase.
Listing licenses and products
Endpoints overview
| Endpoint | HTTP method | Purpose |
|---|---|---|
| GET | Get user licenses | |
| /api/license/v4/products | 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
Allow user to view his licenses
When client can requests 'Get user licenses' endpoint response received contains all of user licenses and also includes all associated products.
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"data": [
{
"id": "42",
"type": "License",
"attributes": {
"status": "ACTIVE",
"start_date": 1523268666,
"stop_date": 1523268698
},
"relationships": {
"user": {
"data": {
"id": "41",
"type": "User"
}
},
"product": {
"data": {
"id": "41",
"type": "Product"
}
}
},
"links": {
"self": "https://boox.fi/api/user/waqqas.jabbar@gmail.com/license/10"
}
}
],
"included": [
{
"id": "41",
"type": "Product",
"attributes": {
"title": "Sport channels meagpack",
"description": "Complete collection fo all sports channels",
"type": "CHANNEL_GROUP",
"is_premium": 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"
}
]
}
}
}
]
} |
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.