Geo & ISP Restrictions API

Overview

The Geo & ISP restriction allows you to include or exclude certain Countries and/or ISPs from the Lumen Delivery Products activation. With these set of APIs, it is possible to Whitelist or Blacklist Countries and/or ISPs where you want CDN Load Balancer to be activated or deactivated depending on your business requirements.

What is a Geo/ISP Restriction List

Empty Lists

While entering data in a field within a list, it is possible to have some fields where no data has been entered, i.e the field is empty. In that case, an empty list corresponds to missing field.

If a field within a list has no data in it, then it is considered to be a missing field.

Example:

This entry,

{
    "name":"test empty ISP whitelist",
    "type":"whitelist",
    "countries": ["United Kingdom"],
    "isp":[]
}

{
    "name":"test empty ISP whitelist",
    "type":"whitelist",
    "countries":["United Kingdom"]
}

Relationships between Countries and ISPs

When calling an API, it is important to keep in mind the relationships between the Countries and ISPs. The relationship differs depending on whether the list has been Blacklisted or Whitelisted. The fields are related in the following way:

Blacklist

• When defining a blacklist, we’ll exclude from the CDN Load Balancer users who belong to the list of Countries OR the list of ISPs
• When a blacklist rule is defined, only the clients whose IP matches the rule are deactivated, all others are activated.

Example

{
    "name":"DNA_Config_1.1",
    "type":"blacklist",
    "countries":["France", "Italy"],
    "isps":["Orange France Mobile", "Wind Tre"]
}

This list will result in all the viewers located in France & Italy (regardless of their ISP) as well as all viewers connected to the Orange France Mobile and Wind Tre (regardless of their country)  being deactivated.

Whitelist

• When defining a blacklist, we’ll exclude from CDN Load Balancer users who belong to the list of Countries AND the list of ISPs
• When a whitelist rule is defined, only the clients whose IP matches the rule are activated, all the rest are deactivated.

Example

{
    ...
    "type":"whitelist",
    "countries":["United Kingdom", "Spain"],
    "isps":["CenturyLink", "Wind Tre"]
}

This list will result in all the viewers located in United Kingdom & Spain who are connected to either Orange France Mobile or Wind Tre being deactivated.

Step by step guide to setup a Geo/ISP Restriction List 

In order to fully setup and implement a Geo/ISP Restriction List using our APIs, follow the following steps:

1. Create a Geo/ISP Restriction List

Create a Geo/ISP Restriction List using the following end-point.

With this end point, you define which countries and/or ISPs would be blacklisted or whitelisted.

2. Attach a Geo/ISP Restriction List to a CDN Load Balancer property

For a Geo/ISP Restriction list to be active, it needs to be attached to a CDN Load Balancer property.

Doing so allows you to implement the rule by calling the Property in your deliveryClientConfig.

Each Property can only have one Geo/ISP Restriction List attached to it so as to avoid conflicts between different Restriction Lists. 

End Point

POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/compass/properties

Request Example

{
    "name": "testGeoIspList",
    "activationRatio": 1,
    "superSeederRatio": 1,
    "detectRangeRequests": true,
    "networkActivation": {
        "wifiEthernetUpload": true,
        "wifiEthernetDownload": true,
        "cellularOtherDownload": true,
        "cellularOtherUpload": true
    },
    "ssai": {
        "enabled": false,
        "provider": "",
        "options": ""
    },
    "geoblockingListId": <YOUR_LIST_ID>
}

Response Example

 {
    "name": "testGeoIspList",
    "activationRatio": 1,
    "cdnListName": "",
    "geoblockingListId": <YOUR_LIST_ID>,
    "cdnScoreProvider": {
        "name": "",
        "credentials": {
            "citrixCustomerID": 0,
            "citrixAppID": 0
        }
    }
}

3. Get the Property the List is attached to

To double check that the setup is successful, you can get the Property that has the Geo & ISP List attached by using the following endpoint:

GET api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/compass/properties/{YOUR_PROPERTY_NAME}

Available APIs

List of API endpoints

 Given below is a list of all the API endpoints that can be used in order to set up Geo/ISP Restriction Lists:

POST // Create a Geo/ISP Restriction List: api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/geo-isp-restrictions/lists

GET // Get all Geo/ISP Restriction Lists:  api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/geo-isp-restrictions/lists

GET // Get one Geo/ISP Restriction List:   api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/geo-isp-restrictions/lists/{{YOUR_LIST_ID}}

PUT // Update a Geo/ISP Restriction List:  api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{{YOUR_LIST_ID}}

DEL //  Delete a Geo/ISP Restriction List: api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{{YOUR_LIST_ID}}

Create a Geo/ISP Restriction List

Allows to define a whitelist or blacklist of countries/ISPs to activate/deactivate CDN Load Balancer.

Endpoint

POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists

For Blacklist

Request Body Example for Blacklist

{
    "name":"DNA_Config_1.1",
    "type":"blacklist",
    "countries":["France", "Italy"],
    "isps":["Orange France Mobile", "Wind Tre"]
}

{
 "data": {
 "countries": [
 "France",
 "Italy"
 ],
 "customerId": <YOUR_CUSTOMER_ID>,
 "id": <YOUR_LIST_ID>,
 "isps": [
 "Orange"
 ],
 "name": "DNA_Config_black_test1",
 "type": "blacklist"
 }
}

For Whitelist

{
    ...
    "type":"whitelist",
    "countries":["United Kingdom", "Spain"],
    "isps":["CenturyLink", "Wind Tre"]
}

{
 "data": {
 "countries": [
 "United Kingdom",
 "Spain"
 ],
 "customerId": <YOUR_CUSTOMER_ID>,
 "id": <YOUR_LIST_ID>,
 "isps": [
 "CenturyLink",
 "Wind Tre"
 ],
 "name": "DNA_Config_white_test2",
 "type": "whitelist"
 }
}

Get a particular Geo/ISP Restriction List

This can be used to get a particular Geo/ISP Restriction List

End Point

GET api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{{YOUR_LIST_ID}}

Response Example

{
    "data": {
        "countries": [
            "france"
        ],
        "customerId": <YOUR_CUSTOMER_ID>,
        "id": <YOUR_LIST_ID>,
        "name": "DNA_Config_1.1",
        "type": "blacklist"
    }
}

Get all Geo/ISP Restriction Lists

This can be used to get all the active Geo/ISP Restriction Lists

End Point

GET api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists

Response Example

{
    "data": [
        {
            "countries": [
                "france"
            ],
            "customerId": <YOUR_CUSTOMER_ID>,
            "id": <YOUR_LIST_ID>,
            "name": "DNA_Config_1.1",
            "type": "blacklist"
        },
        {
            "countries": [
                "france"
            ],
            "customerId": <YOUR_CUSTOMER_ID>,
            "id": <YOUR_LIST_ID>,
            "name": "DNA_Config_1.2",
            "type": "blacklist"
        }
    ]
}

Update a Geo/ISP Restriction List

This can be used to update a particular Geo/ISP Restriction List

End Point

PUT api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{YOUR_LIST_ID}

Request Body Example

{
    "name":"Whitelist (FR) (Orange France Mobile, SFR) - updated",
    "type": "whitelist",
    "countries" : ["France"],
    "isps":["Orange France Mobile", "SFR"]
}

Response Example

Delete a Geo/ISP Restriction List

This can be used to delete a particular Geo/ISP Restriction List.

End Point

DELETE api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{YOUR_LIST_ID}

Response Example

Errors

HTTP 400
{
  "message": "invalid listId"
}

HTTP 500
{
  "error": "empty activation rule is not allowed"
}

Authentication

Authorization: API-Key {YOUR_API_KEY}