Implementation

In order to maintain performance AminoTV is careful not to provide client-specific API responses unless absolutely necessary.

When responding to requests for Channel (or related metadata) information the API will not take the account blocking status or the client blocking status into account.

The client should determine the user preferences and filter information out of the API response.

Unlocking channels for a session

The client should allow the user to specify that all channels should be unlocked for a particular viewing session. The API doesn't have a session concept and only stores a locking configuration that the user chose to set. It is entirely the responsibility of the client to track whether a session has been unlocked in current viewing session.

If the user requests that their session be unlocked through the UI then the client should request that they input their PIN. 

The client can then verify that this PIN is correct by calling

PATCH /api/users/v1/users/<userId>

The request body should look something like this:

{
  "pin_code": "1234",
  "new_pin_code": "1234"
}

Note:

• The API will verify the PIN code supplied against the one stored for the user account and return "403 Forbidden" if an incorrect PIN is supplied
• Note that generally this method is used to update the value of PIN, but when new pin code is the same as old – API will not change any values, but only perform the validation
• No other fields should be supplied;

If the request succeeds then the client can allow the user to view any channel regardless of whether it is listed in their locked list.

The client should lock the channels again after some defined time period.

Fetching the configuration when the user logs in

When the user logs in, the client should call the API to get the current configuration of channel locking on the account. 

GET /users/{user_id}/channel_lock_configuration

This response can be cached for up to 10 minutes.

AminoTV does not currently implement a "push" service to notify clients of updates and therefore the client should periodically refresh the account locking status.

The response will look something like this:

{
  "data": {
    "type": "UserChannelLockingConfiguration",
    "id": "da00a320-2bae-49af-9687-298ed3f01361",
    "attributes": {
      "lock_adult_channels": true,
      "locked_channels": [
        "3bdb869c-4781-46f8-b00b-1a780664a7ab"
      ],
    }
  }
}

This is a list of the id's of channels that are blocked and an indication whether all adult channels must be blocked too.

Adult channels can be included in the locked list too, so when deciding if certain adult channel is to be displayed – consider both boolean flag and whether this channel is in the list. 

In short:

• Adult channel is locked if {{lock_adult_channels}} is true or this channel is in {{locked_channels}}
• Adult channel is unlocked only if {{lock_adult_channels}} is false and this channel is not in {{locked_channels}}
• Non-adult channel is locked if this channel is in {{locked_channels}}

Handling locked channels

The behaviour of the client towards locked channels will largely be determined by the customer specification, but broadly we expect the following to occur in the frontend:

• Some indication is shown to the user that the content item is locked
• The user is prevented from seeing details of the content item
• Thumbnails for the content are replaced with a placeholder that is suitable for general audiences
• The user is prevented from playing the content

It is the responsibility of the client to perform this filtering;  In order to improve performance the API server will not provide user specific responses.

Locking and unlocking channels

The user is able to lock any channel, regardless of its adult rating status.

To change the list of channels that are currently locked the client should call

PATCH /users/{user_id}/channel_lock_configuration

and set the array of locked channels to the desired list.

For example, lets say that the the response to the request that obtained the initial status was:

{
  "locked_channels": [
    "3bdb869c-4781-46f8-b00b-1a780664a7ab", "28ab9e8c-afad-40bc-a353-b6b6ddea9b9d", "05c722d2-d974-424a-acd6-3cd46cf06c8b"
  ]
}

In order to add a new channel to the list the client would use the following request body:

{
  "lock_adult_channels": true,  
  "pin_code": "1234",
  "locked_channels": [
    "3bdb869c-4781-46f8-b00b-1a780664a7ab", "28ab9e8c-afad-40bc-a353-b6b6ddea9b9d", "05c722d2-d974-424a-acd6-3cd46cf06c8b", "89a9fa11-db05-4b72-b9fd-8f57d52196eb"
  ]
}

And to remove that same channel and restore the list to how it was originally the following request body would be used:

{
  "pin_code": "1234",
  "locked_channels": [
    "3bdb869c-4781-46f8-b00b-1a780664a7ab", "28ab9e8c-afad-40bc-a353-b6b6ddea9b9d", "05c722d2-d974-424a-acd6-3cd46cf06c8b"
  ]
}

Note that in both cases when the client makes a change to the entity it is required to provide the valid PIN code

Managing the PIN code

The user may want to change their PIN code.  To facilitate this the client needs to create a request to

PATCH /api/users/v1/users/<userId>

The new PIN code should be supplied in the "new_pin_code" field. 

The API will respond with "400 Bad Request" if the PIN code does not meet the following validation requirements:

• Numeric
• Number of digits must be exactly 4

An example of the PATCH request body is as follows:

{
  "pin_code": "1234",
  "new_pin_code": "0789",
}

Note:

• The API will verify the PIN code supplied against the one stored for the user account and return "403 Forbidden" if an incorrect PIN is supplied
• No other fields should be supplied; the API will respond with "400 Bad Request" if you try to PATCH anything at the same time as the PIN code